Skip to content

Account

Activation, balance, top-up, keys and tier management.

1. Overview

Base path: https://api.infrai.cc/v1/account
Auth header: Authorization: Bearer $INFRAI_API_KEY
bash
# Call any /v1/account capability over raw HTTP — no SDK to install.
# curl:
curl https://api.infrai.cc/v1/account/... \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json"

2. Methods (29)

2.1account.balance

GET /v1/account/balance

Read the wallet balance.

Returns

{ balance_usd, currency }
NameTypeDescription
balancenumberCurrent wallet balance in USD
≥ 0
capnumber | nullWallet upper bound for current tier; null for Enterprise (no cap).
≥ 0
available_roomnumber | null= cap - balance; null when cap is null (uncapped).
≥ 0
runway_daysnumber | nullEstimated days at current daily_avg_spend; null when spend rate is ~0.
≥ 0
daily_avg_spendnumberAverage daily spend in USD
≥ 0
tier"standard" | "pro" | "enterprise"Current subscription tier (standard / pro / enterprise)
expires_atstring | nullTrial-credit expiry (last activity + grace window); null when there is no expiring trial credit.
format: date-time
expires_in_daysinteger | nullDays until the current balance or subscription expires
activity_required_bystring | nullDate by which account activity is required to maintain status
format: date-time
is_refundablebooleanWhether the current balance is eligible for refund
is_transferablebooleanWhether the current balance can be transferred to another account
is_in_grace_periodbooleanWhether the account is in the grace period after balance expiry
grace_period_ends_atstring | nullISO 8601 timestamp when the grace period ends
format: date-time
forfeited_amountnumber | nullAmount forfeited during account operations, in USD
≥ 0
pending_topupsstring[] | nullList of pending top-up sessions
account_idstring | nullThe account the balance belongs to.
balance_usdnumberAlias of `balance` for the documented SDK/CLI status surface.
≥ 0
currencystringISO 4217 currency code (e.g. USD, CNY)
e.g. USD
affordable_uses_hintobject | nullPer-capability hint: how many more flat-priced calls the current balance covers (best-effort, omitted for token-metered caps).

Example

One-time prep (each example is assumed to be complete):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X GET https://api.infrai.cc/v1/account/balance \
  -H "Authorization: Bearer $INFRAI_API_KEY"

2.2account.topup

POST /v1/account/topup

Top up the wallet; returns a checkout URL to hand the user — card data never touches infrai.

Parameters

NameTypeRequiredDescription
amount_usdnumber
Required
Top-up amount in USD.
≥ 0
return_urlstringOptionalWhere to return after checkout.
format: uri
idempotency_keystringOptionalOptional dedup key; identical retries return the same result.

Returns

TopupRecord { topup_id, amount_usd, state, next_action_url? }
NameTypeDescription
topup_idstringProvider checkout-session id (Stripe cs_... / dev cs_mock_...). Pass to account.topup_status to poll the outcome.
status"pending" | "paid" | "failed" | "unknown"pending until the user completes browser checkout; the Stripe webhook flips it to paid/failed.
checkout_urlstringOpen this to pay; on success the wallet is credited.
format: uri
checkout_mode"stripe" | "mock"stripe = real Stripe Checkout; mock = local dev session.
amount_usdnumberTop-up amount in USD.
≥ 0.5
amountnumberBack-compat alias of amount_usd.
≥ 0.5
currencystringISO 4217 currency code (e.g. USD, CNY)
e.g. USD

Example

One-time prep (each example is assumed to be complete):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X POST https://api.infrai.cc/v1/account/topup \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 50, "currency": "USD", "payment_method": "stripe"}'

2.3account.keys.list

GET /v1/account/keys/list

List the project keys on the account.

Returns

{ items: Array<{ key_id, label, scopes, created_at }> }
NameTypeDescription
itemsobject[]Array of result items in this page
items[].key_idstringKey id. On list it is MASKED (optional prefix + separator + last 4) — the separator is ASCII '...' (path-safe) or the legacy unicode ellipsis, e.g. ifr_...52fb / ifr_pk_proj_…9180 / ifr_…ab74. The full ifr_ value is only ever returned at create time.
pattern: ^ifr_[A-Za-z0-9_]*(\.\.\.|\u202…
items[].key_secretstring | nullFull plaintext value; returned only on create.
items[].keystring | nullaccount.keys.rotate only. Full plaintext value of the newly-minted secret, shown exactly once (same purpose as key_secret on create, different field name on this endpoint).
items[].old_key_idstring | nullaccount.keys.rotate only. Masked id of the key that was superseded by this rotation.
items[].rotatedbooleanaccount.keys.rotate only. Whether a new secret was actually minted (false when the referenced key was not found).
items[].revokedbooleanaccount.keys.revoke / .suspected_compromise only. Whether the key was actually revoked (false when the referenced key was not found).
items[].actionstring | nullaccount.keys.suspected_compromise only. Fixed action label, e.g. 'revoked_on_compromise_report'.
items[].updatedbooleanaccount.keys.update only. Whether the key record was actually updated (false when the referenced key was not found).
items[].namestring | nullHuman-readable name for this resource
items[].tierstring | nullBilling tier the key inherits from its account (standard/pro/enterprise).
items[].scopesstring[]Granted scopes. OMITTED from list output (internal; session keys filtered) — present only where the surface exposes it.
items[].created_atstringISO 8601 timestamp when this resource was created
format: date-time
items[].last_used_atstring | nullISO 8601 timestamp when this key was last used
format: date-time
items[].last_used_ipstring | nullIP of the most recent request authenticated with this key; null if never used.
items[].expires_atstring | nullISO 8601 timestamp when this resource or token expires
format: date-time
items[].revoked_atstring | nullISO 8601 timestamp when this key was revoked
format: date-time
items[].status"active" | "rotating" | "revoked" | "not_found"Current status of this resource. 'not_found' is returned by keys.update/.rotate/.suspected_compromise when the referenced key_id doesn't resolve to a key on this account.
next_cursorstring | nullOpaque cursor to fetch the next page; null/absent if this is the last page
countintegerTotal number of items across all pages
≥ 0

Example

One-time prep (each example is assumed to be complete):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X GET https://api.infrai.cc/v1/account/keys/list \
  -H "Authorization: Bearer $INFRAI_API_KEY"

2.4account.tier.upgrade

POST /v1/account/tier/upgrade

Upgrade the account to a target tier.

Parameters

NameTypeRequiredDescription
target_tierstring
Required
Tier id to upgrade to.

Returns

AccountSummary { account_id, kind, status, tier, balance_usd }
NameTypeDescription
target"pro" | "team" | "enterprise"Target URL or resource for webhook or notification
requires_checkoutbooleanWhether a Stripe checkout session is required to complete the change
checkout_urlstring | nullURL for the Stripe checkout session
format: uri
requires_sales_contactbooleanWhether contacting sales is required to complete the change
contact_sales_urlstring | nullURL to contact the sales team
format: uri
current_tierstring | nullEffective tier before this upgrade.
status"pending" | "active" | nullSubscription lifecycle after the call. pending = awaiting checkout webhook; active = confirmed (dev/non-prod posture).
immediate_effectboolean | nullTrue only when the tier flipped immediately (dev/non-prod posture, no real payment).
price_usdnumber | nullResolved plan price in USD.
periodstring | nullBilling period of the resolved plan (e.g. monthly/annual).
subscriptionobject | nullPublic view of the created subscription (present when confirmed).
subscription_idstring | nullCreated subscription id (present when pending checkout).
payment_source"wallet" | "dev_mock" | "stripe_subscription" | nullHow the upgrade was (or will be) funded: wallet balance, dev/non-prod auto-confirm, or a real Stripe subscription checkout. Absent for the enterprise (sales-contact) branch.
checkout_modestring | nullMode of the created checkout session (e.g. 'stripe'/'mock'). Present only alongside checkout_url (payment_source=stripe_subscription).
account_idstring | nullAccount the upgrade applies to.

Example

One-time prep (each example is assumed to be complete):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X POST https://api.infrai.cc/v1/account/tier/upgrade \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target": "pro"}'

2.5account.whoami

GET /v1/account/whoami

Get the current account summary (account ID, type, status, tier, balance).

Returns

AccountSummary { account_id, kind, status, tier, balance_usd }
NameTypeDescription
account_idstringReal ids use a 16-hex device/email suffix (e.g. acct_anon_9424f4c4b31d4908); pattern relaxed to a minimum of 12 hex chars to match the live id format.
pattern: ^acct_(anon|email|unbound)_[A-Z…
account_kind"anonymous" | "email" | "unbound"Identity state of the key holder. `unbound` = key minted by infra.activate() not yet linked to an email; `email` = bound via OTP/Google/GitHub. `anonymous` is a legacy alias for `unbound` (will be retired).
emailstring | nullEmail address
format: email
email_verifiedbooleanWhether the email address has been verified
linked_providers("email_otp" | "google" | "github" | "oauth")[]Identity providers that have verified this email. The same email can be linked via multiple methods (Google + GitHub + OTP) and all resolve to one account. Empty for unbound keys.
display_namestring | nullHuman-readable display name
region"global" | "cn"Geographic region where this resource is located or processed
created_atstring | nullUser-row creation time. Null for unbound keys (no User row yet).
format: date-time
last_active_atstring | nullLatest of last_login_at / updated_at on the User row. Null for unbound keys.
format: date-time
tier"standard" | "pro" | "enterprise"Current subscription tier (standard / pro / enterprise)
kyc_status"none" | "pending" | "approved" | "rejected"Current KYC verification status
totp_enabledbooleanWhether TOTP-based 2FA is enabled for this account
pro_subscriptionobject | nullDetails of the active Pro subscription, if any
enterprise_contractobject | nullDetails of the enterprise contract, if any
device_fingerprintstringDevice fingerprint hash for identity tracking
current_project_key_idstringCurrent project key identifier
project_countintegerNumber of projects in this account
≥ 0
absorbed_anon_account_idsstring[]List of anonymous account IDs absorbed during linking
linked_devices_countintegerNumber of linked device accounts
≥ 0
project_idstring | nullThe project_id the caller's bearer key is bound to. Mirrors api_key.project_id (e.g. `proj_anon_xxx` for an unbound key). Null when the bearer has no project.
key_idstring | nullMasked (non-secret) form of the caller's bearer key — same value as `current_project_key_id`. Kept for compatibility with the original `account.whoami` shape; new callers should read `current_project_key_id`.

Example

One-time prep (each example is assumed to be complete):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X GET https://api.infrai.cc/v1/account/whoami \
  -H "Authorization: Bearer $INFRAI_API_KEY"

2.6account.usage

GET /v1/account/usage

Get the usage summary (consumption, number of requests, split by capability) for this billing cycle.

Returns

UsageSummary { period, spend_usd, requests, by_capability }
NameTypeDescription
period"1d" | "7d" | "30d" | "mtd" | "ytd"Billing or retention period (e.g. monthly, daily)
period_startstringStart of the current billing period
format: date-time
period_endstringEnd of the current billing period
format: date-time
total_costnumberTotal cost in USD for the queried period
≥ 0
total_callsintegerTotal number of API calls in the queried period
≥ 0
total_failed_callsintegerTotal number of failed API calls in the queried period
≥ 0
cache_hitsintegerNumber of cache hits in the queried period
≥ 0
cache_savingsnumberEstimated cost savings from cache hits in USD
≥ 0
breakdownobject[]Cost breakdown by component
breakdown[].keystring-
breakdown[].labelstring-
breakdown[].costnumber-
≥ 0
breakdown[].callsinteger-
≥ 0
breakdown[].failed_callsinteger-
≥ 0
breakdown[].avg_latency_msnumber | null-
≥ 0
breakdown[].p95_latency_msnumber | null-
≥ 0
breakdown[].error_ratenumber | null-
0–1
breakdown[].top_errorsobject[] | null-

Example

One-time prep (each example is assumed to be complete):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X GET https://api.infrai.cc/v1/account/usage \
  -H "Authorization: Bearer $INFRAI_API_KEY"

2.7account.usage.timeseries

GET /v1/account/usage/timeseries

Get the usage time series by time granularity.

Parameters

NameTypeRequiredDescription
startstringOptionalStarting time (ISO 8601), if left blank, the starting point of the cycle will be taken.
endstringOptionalEnd time (ISO 8601), if left blank, the current time will be used.
granularity"hour" | "day" | "month"OptionalAggregation granularity: hour/day/month.

Returns

UsageTimeseries { granularity, points: Array<{ ts, spend_usd, requests }> }
NameTypeDescription
period"1d" | "7d" | "30d" | "mtd" | "ytd"Billing or retention period (e.g. monthly, daily)
bucketsobject[]Time-bucketed data points
buckets[].datestring-
format: date
buckets[].costnumber-
≥ 0
buckets[].callsinteger-
≥ 0
buckets[].failed_callsinteger-
≥ 0
buckets[].cache_hitsinteger | null-
≥ 0
next_cursorstring | nullOpaque cursor to fetch the next page; null/absent if this is the last page

Example

One-time prep (each example is assumed to be complete):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X GET https://api.infrai.cc/v1/account/usage/timeseries \
  -H "Authorization: Bearer $INFRAI_API_KEY"

2.8account.budget.get

GET /v1/account/budget/get

Get the current budget configuration (period, hard cap, alarm threshold).

Returns

BudgetConfig { period, hard_cap_usd?, alert_threshold_usd? }
NameTypeDescription
hard_cap_usdnumber | nullSpend in the period is blocked past this; null = no cap.
≥ 0
period"daily" | "monthly"Billing or retention period (e.g. monthly, daily)
alert_threshold_usdnumber | nullFire low-balance / budget-near alert at this remaining balance; null = no alert.
≥ 0
spent_this_period_usdnumberAmount spent in the current billing period in USD
≥ 0
period_resets_atstring | nullISO 8601 timestamp when the current period resets
format: date-time
configuredbooleanWhether a budget row has been set (false = no cap configured; the *_usd fields are then null/0).
updated_atstring | nullISO 8601 timestamp when this resource was last updated
format: date-time

Example

One-time prep (each example is assumed to be complete):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X GET https://api.infrai.cc/v1/account/budget/get \
  -H "Authorization: Bearer $INFRAI_API_KEY"

2.9account.budget.set

PUT /v1/account/budget/set

Set a budget: when consumption reaches the hard upper limit within the cycle, it will be intercepted, and when consumption reaches the threshold, an alarm will be issued.

Parameters

NameTypeRequiredDescription
period"daily" | "monthly"
Required
Budget period: daily or monthly.
hard_cap_usdnumberOptionalHard upper limit (USD), beyond which subsequent billing requests will be blocked.
≥ 0
alert_threshold_usdnumberOptionalAlarm threshold (USD), when reached, an alarm is triggered.
≥ 0
idempotency_keystringOptionalOptional dedup key; identical retries return the same result.

Returns

BudgetConfig { period, hard_cap_usd?, alert_threshold_usd? }
NameTypeDescription
hard_cap_usdnumber | nullSpend in the period is blocked past this; null = no cap.
≥ 0
period"daily" | "monthly"Billing or retention period (e.g. monthly, daily)
alert_threshold_usdnumber | nullFire low-balance / budget-near alert at this remaining balance; null = no alert.
≥ 0
spent_this_period_usdnumberAmount spent in the current billing period in USD
≥ 0
period_resets_atstring | nullISO 8601 timestamp when the current period resets
format: date-time
configuredbooleanWhether a budget row has been set (false = no cap configured; the *_usd fields are then null/0).
updated_atstring | nullISO 8601 timestamp when this resource was last updated
format: date-time

Example

One-time prep (each example is assumed to be complete):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X PUT https://api.infrai.cc/v1/account/budget/set \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hard_cap_usd": "sample", "period": "daily"}'

2.10account.autorecharge.get

GET /v1/account/autorecharge/get

Get automatic recharge configuration.

Returns

AutorechargeConfig { enabled, trigger_balance, recharge_amount, max_per_day, max_per_month }
NameTypeDescription
enabledbooleanWhether this feature or configuration is enabled
trigger_balancenumberBalance threshold that triggers automatic recharge, in USD
≥ 0
recharge_amountnumberAmount to recharge when triggered, in USD
≥ 0
payment_method_idstringIdentifier of the payment method used
payment_method_summarystringe.g. 'Visa ****4242'.
max_per_dayintegerMaximum recharge amount per day in USD
≥ 1
max_per_monthintegerMaximum recharge amount per month in USD
≥ 1
triggered_todayintegerAmount recharged today in USD
≥ 0
triggered_this_monthintegerAmount recharged this month in USD
≥ 0
next_check_atstring | nullISO 8601 timestamp when the next balance check will occur
format: date-time
last_succeeded_atstring | nullISO 8601 timestamp of the last successful payment
format: date-time
last_failed_atstring | nullISO 8601 timestamp of the last payment failure
format: date-time
consecutive_failuresintegerNumber of consecutive payment failures
≥ 0
configuredbooleanWhether a config row exists for this account (false = never set up; the numeric fields are then zero defaults).
disabled_reasonstring | nullWhy auto-recharge is currently disabled (e.g. 'user', 'max_failures', 'admin'); null when enabled or never disabled.

Example

One-time prep (each example is assumed to be complete):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X GET https://api.infrai.cc/v1/account/autorecharge/get \
  -H "Authorization: Bearer $INFRAI_API_KEY"

2.11account.autorecharge.configure

PUT /v1/account/autorecharge/configure

Configure automatic recharge: Automatically deduct and recharge when the balance is lower than the trigger value.

Parameters

NameTypeRequiredDescription
trigger_balancenumber
Required
Trigger balance: When the wallet balance is lower than this value, it will be automatically recharged.
≥ 0
recharge_amountnumber
Required
The amount of each automatic top-up (USD).
> 0
payment_method_idstringOptionalDebit payment method ID. If left blank, the account default payment method will be used.
max_per_daynumberOptionalMaximum number of automatic recharges per day (to prevent abuse).
≥ 1default: 3
max_per_monthnumberOptionalMaximum number of automatic recharges per month (to prevent abuse).
≥ 1default: 30
idempotency_keystringOptionalOptional dedup key; identical retries return the same result.

Returns

AutorechargeConfig { enabled, trigger_balance, recharge_amount, max_per_day, max_per_month }
NameTypeDescription
enabledbooleanWhether this feature or configuration is enabled
trigger_balancenumberBalance threshold that triggers automatic recharge, in USD
≥ 0
recharge_amountnumberAmount to recharge when triggered, in USD
≥ 0
payment_method_idstringIdentifier of the payment method used
payment_method_summarystringe.g. 'Visa ****4242'.
max_per_dayintegerMaximum recharge amount per day in USD
≥ 1
max_per_monthintegerMaximum recharge amount per month in USD
≥ 1
triggered_todayintegerAmount recharged today in USD
≥ 0
triggered_this_monthintegerAmount recharged this month in USD
≥ 0
next_check_atstring | nullISO 8601 timestamp when the next balance check will occur
format: date-time
last_succeeded_atstring | nullISO 8601 timestamp of the last successful payment
format: date-time
last_failed_atstring | nullISO 8601 timestamp of the last payment failure
format: date-time
consecutive_failuresintegerNumber of consecutive payment failures
≥ 0
configuredbooleanWhether a config row exists for this account (false = never set up; the numeric fields are then zero defaults).
disabled_reasonstring | nullWhy auto-recharge is currently disabled (e.g. 'user', 'max_failures', 'admin'); null when enabled or never disabled.

Example

One-time prep (each example is assumed to be complete):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X PUT https://api.infrai.cc/v1/account/autorecharge/configure \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"trigger_balance": 1.0, "recharge_amount": 1.0}'

2.12account.payment_method.set_default

POST /v1/account/payment_method/set_default

Set the specified payment method as the account default.

Parameters

NameTypeRequiredDescription
payment_method_idstring
Required
The payment method ID to set as the default.
idempotency_keystringOptionalOptional dedup key; identical retries return the same result.

Returns

AccountPaymentMethod { id, brand, last4, is_default }
NameTypeDescription
payment_method_idstringIdentifier of the payment method used
set_defaultbooleanaccount.payment_method.set_default only. Whether the default was actually changed (false when payment_method_id isn't a known saved method).
status"not_found" | nullaccount.payment_method.set_default only. Present ('not_found') when payment_method_id doesn't match a saved method.
messagestring | nullaccount.payment_method.set_default only. Human-readable detail when set_default is false.
kind"card" | "sepa" | "ach" | "alipay" | "wechat" | "applepay" | "googlepay" | nullOptional. Structured instrument kind; absent for cards saved via the setup-intent flow (only the provider summary is retained) — see `summary`.
summarystring | nullHuman-readable description of the instrument, e.g. 'Visa ****4242'.
stripe_customer_idstring | nullStripe customer id the method is attached to; null in mock/dev.
is_defaultbooleanWhether this is the default payment method
last4string | nullLast 4 digits of the card number
pattern: ^[0-9]{4}$
brandstring | nullCard brand (e.g. visa, mastercard)
expiresstring | nullMM/YY for card kind.
added_atstring | nullISO 8601 timestamp when this resource was added
format: date-time

Example

One-time prep (each example is assumed to be complete):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X POST https://api.infrai.cc/v1/account/payment_method/set_default \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"payment_method_id": "sample"}'

2.13account.tier

GET /v1/account/tier

Get the current account level and its limit.

Returns

TierInfo { tier, limits, billing_period }
NameTypeDescription
tier"standard" | "pro" | "enterprise"Current subscription tier (standard / pro / enterprise)
sincestringISO 8601 date when the current tier or state became effective
format: date-time
wallet_capnumber | nullnull for Enterprise (no cap).
≥ 0
rate_limit_multipliernumberRate limit multiplier applied at this tier
≥ 1
featuresstring[]List of features available at this tier
pro_subscriptionobject | nullDetails of the active Pro subscription, if any
enterprise_contractobject | nullDetails of the enterprise contract, if any
account_idstring | nullThe account whose tier this is.

Example

One-time prep (each example is assumed to be complete):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X GET https://api.infrai.cc/v1/account/tier \
  -H "Authorization: Bearer $INFRAI_API_KEY"

2.14account.subscription.get

GET /v1/account/subscription/get

Get the subscription status (slot, current cycle end time, whether it will be cancelled).

Returns

SubscriptionInfo { status, tier, current_period_end, cancel_at_period_end }
NameTypeDescription
model"usage_based"Always usage_based; pay-as-you-go wallet with optional auto-recharge.
tier"standard" | "pro" | "enterprise"Current subscription tier (standard / pro / enterprise)
fixed_subscriptionobject | nullReserved for a future fixed recurring plan; null today (no fixed subscription).
autorechargeobjectThe recurring funding policy: auto top-up of the wallet when it drops below trigger_balance_usd.
autorecharge.enabledboolean-
autorecharge.recharge_amount_usdnumber | null-
≥ 0
autorecharge.trigger_balance_usdnumber | null-
≥ 0
autorecharge.payment_methodstring | nullMasked card summary, e.g. 'Visa ****4242'.

Example

One-time prep (each example is assumed to be complete):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X GET https://api.infrai.cc/v1/account/subscription/get \
  -H "Authorization: Bearer $INFRAI_API_KEY"

2.15account.keys.create

POST /v1/account/keys/create

Create API Key, key_secret is returned only once when created.

Parameters

NameTypeRequiredDescription
namestringOptionalKey name (maximum 128 characters).
≤ 128 chars
scopesstring[]OptionalScope list, leave blank to indicate the entire module.
idempotency_keystringOptionalOptional dedup key; identical retries return the same result.

Returns

ApiKey { key_id, name, scopes, key_secret, created_at }
NameTypeDescription
key_idstringKey id. On list it is MASKED (optional prefix + separator + last 4) — the separator is ASCII '...' (path-safe) or the legacy unicode ellipsis, e.g. ifr_...52fb / ifr_pk_proj_…9180 / ifr_…ab74. The full ifr_ value is only ever returned at create time.
pattern: ^ifr_[A-Za-z0-9_]*(\.\.\.|\u202…
key_secretstring | nullFull plaintext value; returned only on create.
keystring | nullaccount.keys.rotate only. Full plaintext value of the newly-minted secret, shown exactly once (same purpose as key_secret on create, different field name on this endpoint).
old_key_idstring | nullaccount.keys.rotate only. Masked id of the key that was superseded by this rotation.
rotatedbooleanaccount.keys.rotate only. Whether a new secret was actually minted (false when the referenced key was not found).
revokedbooleanaccount.keys.revoke / .suspected_compromise only. Whether the key was actually revoked (false when the referenced key was not found).
actionstring | nullaccount.keys.suspected_compromise only. Fixed action label, e.g. 'revoked_on_compromise_report'.
updatedbooleanaccount.keys.update only. Whether the key record was actually updated (false when the referenced key was not found).
namestring | nullHuman-readable name for this resource
tierstring | nullBilling tier the key inherits from its account (standard/pro/enterprise).
scopesstring[]Granted scopes. OMITTED from list output (internal; session keys filtered) — present only where the surface exposes it.
created_atstringISO 8601 timestamp when this resource was created
format: date-time
last_used_atstring | nullISO 8601 timestamp when this key was last used
format: date-time
last_used_ipstring | nullIP of the most recent request authenticated with this key; null if never used.
expires_atstring | nullISO 8601 timestamp when this resource or token expires
format: date-time
revoked_atstring | nullISO 8601 timestamp when this key was revoked
format: date-time
status"active" | "rotating" | "revoked" | "not_found"Current status of this resource

Example

One-time prep (each example is assumed to be complete):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X POST https://api.infrai.cc/v1/account/keys/create \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

2.16account.keys.update

PATCH /v1/account/keys/update/{id}

Update the name and/or scope of the API Key, and the scope tightening will take effect immediately.

Parameters

NameTypeRequiredDescription
key_idstring
Required
API Key ID。
namestringOptionalNew Key name.
≤ 128 chars
scopesstring[]OptionalList of new scopes.
idempotency_keystringOptionalOptional dedup key; identical retries return the same result.

Returns

ApiKey { key_id, name, scopes }
NameTypeDescription
key_idstringKey id. On list it is MASKED (optional prefix + separator + last 4) — the separator is ASCII '...' (path-safe) or the legacy unicode ellipsis, e.g. ifr_...52fb / ifr_pk_proj_…9180 / ifr_…ab74. The full ifr_ value is only ever returned at create time.
pattern: ^ifr_[A-Za-z0-9_]*(\.\.\.|\u202…
key_secretstring | nullFull plaintext value; returned only on create.
keystring | nullaccount.keys.rotate only. Full plaintext value of the newly-minted secret, shown exactly once (same purpose as key_secret on create, different field name on this endpoint).
old_key_idstring | nullaccount.keys.rotate only. Masked id of the key that was superseded by this rotation.
rotatedbooleanaccount.keys.rotate only. Whether a new secret was actually minted (false when the referenced key was not found).
revokedbooleanaccount.keys.revoke / .suspected_compromise only. Whether the key was actually revoked (false when the referenced key was not found).
actionstring | nullaccount.keys.suspected_compromise only. Fixed action label, e.g. 'revoked_on_compromise_report'.
updatedbooleanaccount.keys.update only. Whether the key record was actually updated (false when the referenced key was not found).
namestring | nullHuman-readable name for this resource
tierstring | nullBilling tier the key inherits from its account (standard/pro/enterprise).
scopesstring[]Granted scopes. OMITTED from list output (internal; session keys filtered) — present only where the surface exposes it.
created_atstringISO 8601 timestamp when this resource was created
format: date-time
last_used_atstring | nullISO 8601 timestamp when this key was last used
format: date-time
last_used_ipstring | nullIP of the most recent request authenticated with this key; null if never used.
expires_atstring | nullISO 8601 timestamp when this resource or token expires
format: date-time
revoked_atstring | nullISO 8601 timestamp when this key was revoked
format: date-time
status"active" | "rotating" | "revoked" | "not_found"Current status of this resource

Example

One-time prep (each example is assumed to be complete):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X PATCH https://api.infrai.cc/v1/account/keys/update/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

2.17account.keys.rotate

POST /v1/account/keys/rotate/{id}

Rotate API Key: A new key is issued and the old key remains valid during the grace period.

Parameters

NameTypeRequiredDescription
key_idstring
Required
API Key ID。
grace_hoursnumberOptionalNumber of hours old key grace is valid (0-168, default 24).
0–168default: 24
idempotency_keystringOptionalOptional dedup key; identical retries return the same result.

Returns

ApiKey { key_id, key_secret, status, grace_expires_at }
NameTypeDescription
key_idstringKey id. On list it is MASKED (optional prefix + separator + last 4) — the separator is ASCII '...' (path-safe) or the legacy unicode ellipsis, e.g. ifr_...52fb / ifr_pk_proj_…9180 / ifr_…ab74. The full ifr_ value is only ever returned at create time.
pattern: ^ifr_[A-Za-z0-9_]*(\.\.\.|\u202…
key_secretstring | nullFull plaintext value; returned only on create.
keystring | nullaccount.keys.rotate only. Full plaintext value of the newly-minted secret, shown exactly once (same purpose as key_secret on create, different field name on this endpoint).
old_key_idstring | nullaccount.keys.rotate only. Masked id of the key that was superseded by this rotation.
rotatedbooleanaccount.keys.rotate only. Whether a new secret was actually minted (false when the referenced key was not found).
revokedbooleanaccount.keys.revoke / .suspected_compromise only. Whether the key was actually revoked (false when the referenced key was not found).
actionstring | nullaccount.keys.suspected_compromise only. Fixed action label, e.g. 'revoked_on_compromise_report'.
updatedbooleanaccount.keys.update only. Whether the key record was actually updated (false when the referenced key was not found).
namestring | nullHuman-readable name for this resource
tierstring | nullBilling tier the key inherits from its account (standard/pro/enterprise).
scopesstring[]Granted scopes. OMITTED from list output (internal; session keys filtered) — present only where the surface exposes it.
created_atstringISO 8601 timestamp when this resource was created
format: date-time
last_used_atstring | nullISO 8601 timestamp when this key was last used
format: date-time
last_used_ipstring | nullIP of the most recent request authenticated with this key; null if never used.
expires_atstring | nullISO 8601 timestamp when this resource or token expires
format: date-time
revoked_atstring | nullISO 8601 timestamp when this key was revoked
format: date-time
status"active" | "rotating" | "revoked" | "not_found"Current status of this resource

Example

One-time prep (each example is assumed to be complete):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X POST https://api.infrai.cc/v1/account/keys/rotate/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

2.18account.keys.revoke

DELETE /v1/account/keys/revoke/{id}

Revoke the API Key and it will become invalid immediately.

Parameters

NameTypeRequiredDescription
key_idstring
Required
API Key ID。
idempotency_keystringOptionalOptional dedup key; identical retries return the same result.

Returns

{ revoked: boolean }
NameTypeDescription
key_idstringKey id. On list it is MASKED (optional prefix + separator + last 4) — the separator is ASCII '...' (path-safe) or the legacy unicode ellipsis, e.g. ifr_...52fb / ifr_pk_proj_…9180 / ifr_…ab74. The full ifr_ value is only ever returned at create time.
pattern: ^ifr_[A-Za-z0-9_]*(\.\.\.|\u202…
key_secretstring | nullFull plaintext value; returned only on create.
keystring | nullaccount.keys.rotate only. Full plaintext value of the newly-minted secret, shown exactly once (same purpose as key_secret on create, different field name on this endpoint).
old_key_idstring | nullaccount.keys.rotate only. Masked id of the key that was superseded by this rotation.
rotatedbooleanaccount.keys.rotate only. Whether a new secret was actually minted (false when the referenced key was not found).
revokedbooleanaccount.keys.revoke / .suspected_compromise only. Whether the key was actually revoked (false when the referenced key was not found).
actionstring | nullaccount.keys.suspected_compromise only. Fixed action label, e.g. 'revoked_on_compromise_report'.
updatedbooleanaccount.keys.update only. Whether the key record was actually updated (false when the referenced key was not found).
namestring | nullHuman-readable name for this resource
tierstring | nullBilling tier the key inherits from its account (standard/pro/enterprise).
scopesstring[]Granted scopes. OMITTED from list output (internal; session keys filtered) — present only where the surface exposes it.
created_atstringISO 8601 timestamp when this resource was created
format: date-time
last_used_atstring | nullISO 8601 timestamp when this key was last used
format: date-time
last_used_ipstring | nullIP of the most recent request authenticated with this key; null if never used.
expires_atstring | nullISO 8601 timestamp when this resource or token expires
format: date-time
revoked_atstring | nullISO 8601 timestamp when this key was revoked
format: date-time
status"active" | "rotating" | "revoked" | "not_found"Current status of this resource

Example

One-time prep (each example is assumed to be complete):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X DELETE https://api.infrai.cc/v1/account/keys/revoke/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

2.19account.keys.suspected_compromise

POST /v1/account/keys/suspected_compromise/{id}

If a suspected API Key leak is reported, it can be immediately revoked and a replacement key automatically issued.

Parameters

NameTypeRequiredDescription
key_idstring
Required
API Key ID。
confirmed_leakbooleanOptionalWhether the leak has been confirmed, if true, it will be revoked immediately.
default: false
auto_rotatebooleanOptionalWhether to automatically issue replacement keys.
default: true
idempotency_keystringOptionalOptional dedup key; identical retries return the same result.

Returns

ApiKey { key_id, status, key_secret? }
NameTypeDescription
key_idstringKey id. On list it is MASKED (optional prefix + separator + last 4) — the separator is ASCII '...' (path-safe) or the legacy unicode ellipsis, e.g. ifr_...52fb / ifr_pk_proj_…9180 / ifr_…ab74. The full ifr_ value is only ever returned at create time.
pattern: ^ifr_[A-Za-z0-9_]*(\.\.\.|\u202…
key_secretstring | nullFull plaintext value; returned only on create.
keystring | nullaccount.keys.rotate only. Full plaintext value of the newly-minted secret, shown exactly once (same purpose as key_secret on create, different field name on this endpoint).
old_key_idstring | nullaccount.keys.rotate only. Masked id of the key that was superseded by this rotation.
rotatedbooleanaccount.keys.rotate only. Whether a new secret was actually minted (false when the referenced key was not found).
revokedbooleanaccount.keys.revoke / .suspected_compromise only. Whether the key was actually revoked (false when the referenced key was not found).
actionstring | nullaccount.keys.suspected_compromise only. Fixed action label, e.g. 'revoked_on_compromise_report'.
updatedbooleanaccount.keys.update only. Whether the key record was actually updated (false when the referenced key was not found).
namestring | nullHuman-readable name for this resource
tierstring | nullBilling tier the key inherits from its account (standard/pro/enterprise).
scopesstring[]Granted scopes. OMITTED from list output (internal; session keys filtered) — present only where the surface exposes it.
created_atstringISO 8601 timestamp when this resource was created
format: date-time
last_used_atstring | nullISO 8601 timestamp when this key was last used
format: date-time
last_used_ipstring | nullIP of the most recent request authenticated with this key; null if never used.
expires_atstring | nullISO 8601 timestamp when this resource or token expires
format: date-time
revoked_atstring | nullISO 8601 timestamp when this key was revoked
format: date-time
status"active" | "rotating" | "revoked" | "not_found"Current status of this resource

Example

One-time prep (each example is assumed to be complete):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X POST https://api.infrai.cc/v1/account/keys/suspected_compromise/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

2.20account.webhooks.list

GET /v1/account/webhooks/list

Paginated list of registered webhooks.

Parameters

NameTypeRequiredDescription
cursorstringOptionalPaging cursor: Pass in the next_cursor returned from the previous page to get the next page.
limitnumberOptionalThe maximum number of items returned on a single page.

Returns

{ items: Array<Webhook>, next_cursor? }
NameTypeDescription
itemsobject[]Array of result items in this page
items[].webhook_idstringWebhook subscription id (whk_… in the account_resource store).
pattern: ^whk?_[A-Za-z0-9]{16,}$
items[].urlstringURL for this resource or endpoint
format: uri
items[].eventsstring[]Event names per enums/webhook_event.yaml.
items[].descriptionstring | nullFree-text description of this resource
items[].secretstring | nullPlaintext secret — returned only on initial create.
items[].secret_hashstring | nullSHA-256 hex of secret; returned on list/get.
items[].activebooleanWhether deliveries are sent. Canonical state field.
items[].enabledboolean | nullBack-compat alias of `active` (console reads this).
items[].statusstring | nullaccount_resource lifecycle status (e.g. 'active').
items[].retry_policy"default" | "aggressive" | nullRetry policy configuration
items[].headersobject | nullCustom HTTP headers added to every delivery.
items[].last_delivery_atstring | nullISO 8601 timestamp of the last delivery attempt
format: date-time
items[].last_delivery_status"success" | "failed" | nullStatus of the last delivery attempt
items[].failure_count_24hintegerNumber of failed deliveries in the last 24 hours
≥ 0
items[].auto_disabled_atstring | nullSet when 100 consecutive failures triggered auto-disable.
format: date-time
items[].created_atstring | nullISO 8601 timestamp when this resource was created. Absent on account.webhooks.update (patch response echoes updated_at only).
format: date-time
items[].updated_atstring | nullISO 8601 timestamp when this resource was last updated. Returned by .get/.update; absent on .register/.list.
format: date-time
next_cursorstring | nullOpaque cursor to fetch the next page; null/absent if this is the last page
countintegerTotal number of items across all pages
≥ 0

Example

One-time prep (each example is assumed to be complete):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X GET https://api.infrai.cc/v1/account/webhooks/list \
  -H "Authorization: Bearer $INFRAI_API_KEY"

2.21account.webhooks.register

POST /v1/account/webhooks/register

To register a Webhook, the URL must be a public https endpoint (the server performs SSRF verification), and the secret will only be returned once.

Parameters

NameTypeRequiredDescription
urlstring
Required
The public https address to receive callbacks.
format: uri
events("account.created" | "account.updated" | "account.absorbed" | "account.device_linked" | "account.deleted" | "topup.succeeded" | "topup.failed" | "topup.review_started" | "autorecharge.charged" | "autorecharge.failed" | "subscription.activated" | "subscription.renewed" | "subscription.cancelled" | "kyc.status_changed" | "tier.upgraded" | "tier.downgraded" | "wallet.low_balance" | "wallet.expiring_soon" | "wallet.expired" | "email.queued" | "email.sent" | "email.delivered" | "email.opened" | "email.clicked" | "email.bounced" | "email.complained" | "email.deferred" | "email.cancelled" | "email.unsubscribed" | "email.auto_suppressed" | "sms.queued" | "sms.sent" | "sms.delivered" | "sms.failed" | "sms.inbound" | "image.job.completed" | "image.job.failed" | "video.job.completed" | "video.job.failed" | "ai.batch.completed" | "ai.batch.failed" | "captcha.verified" | "captcha.failed" | "realtime.channel.occupied" | "realtime.channel.vacated" | "realtime.member.added" | "realtime.member.removed" | "cron.executed" | "cron.failed" | "cron.missed" | "queue.dlq" | "observability.alert.fired" | "error.captured" | "error.rate_anomaly" | "system.vendor.down" | "system.maintenance.scheduled")[]
Required
List of event types to subscribe to.
≥ 1 item
descriptionstringOptionalNotes (optional, up to 256 characters).
≤ 256 chars
secretstringOptionalCustomize the signing key, leave it blank to automatically generate it.
retry_policy"default" | "aggressive" | nullOptionalRetry policy: default or aggressive.
headersRecord<string, string>OptionalAdditional custom HTTP headers for each delivery.
idempotency_keystringOptionalOptional dedup key; identical retries return the same result.

Returns

Webhook { id, url, events, secret, active }
NameTypeDescription
webhook_idstringWebhook subscription id (whk_… in the account_resource store).
pattern: ^whk?_[A-Za-z0-9]{16,}$
urlstringURL for this resource or endpoint
format: uri
eventsstring[]Event names per enums/webhook_event.yaml.
descriptionstring | nullFree-text description of this resource
secretstring | nullPlaintext secret — returned only on initial create.
secret_hashstring | nullSHA-256 hex of secret; returned on list/get.
activebooleanWhether deliveries are sent. Canonical state field.
enabledboolean | nullBack-compat alias of `active` (console reads this).
statusstring | nullaccount_resource lifecycle status (e.g. 'active').
retry_policy"default" | "aggressive" | nullRetry policy configuration
headersobject | nullCustom HTTP headers added to every delivery.
last_delivery_atstring | nullISO 8601 timestamp of the last delivery attempt
format: date-time
last_delivery_status"success" | "failed" | nullStatus of the last delivery attempt
failure_count_24hintegerNumber of failed deliveries in the last 24 hours
≥ 0
auto_disabled_atstring | nullSet when 100 consecutive failures triggered auto-disable.
format: date-time
created_atstring | nullISO 8601 timestamp when this resource was created
format: date-time
updated_atstring | nullISO 8601 timestamp when this resource was last updated. Returned by .get/.update; absent on .register/.list.
format: date-time

Example

One-time prep (each example is assumed to be complete):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X POST https://api.infrai.cc/v1/account/webhooks/register \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/callback", "events": ["account.created"]}'

2.22account.webhooks.get

GET /v1/account/webhooks/get/{id}

Get individual webhook details.

Parameters

NameTypeRequiredDescription
webhook_idstring
Required
Webhook ID。

Returns

Webhook { id, url, events, active, retry_policy }
NameTypeDescription
webhook_idstringWebhook subscription id (whk_… in the account_resource store).
pattern: ^whk?_[A-Za-z0-9]{16,}$
urlstringURL for this resource or endpoint
format: uri
eventsstring[]Event names per enums/webhook_event.yaml.
descriptionstring | nullFree-text description of this resource
secretstring | nullPlaintext secret — returned only on initial create.
secret_hashstring | nullSHA-256 hex of secret; returned on list/get.
activebooleanWhether deliveries are sent. Canonical state field.
enabledboolean | nullBack-compat alias of `active` (console reads this).
statusstring | nullaccount_resource lifecycle status (e.g. 'active').
retry_policy"default" | "aggressive" | nullRetry policy configuration
headersobject | nullCustom HTTP headers added to every delivery.
last_delivery_atstring | nullISO 8601 timestamp of the last delivery attempt
format: date-time
last_delivery_status"success" | "failed" | nullStatus of the last delivery attempt
failure_count_24hintegerNumber of failed deliveries in the last 24 hours
≥ 0
auto_disabled_atstring | nullSet when 100 consecutive failures triggered auto-disable.
format: date-time
created_atstring | nullISO 8601 timestamp when this resource was created
format: date-time
updated_atstring | nullISO 8601 timestamp when this resource was last updated. Returned by .get/.update; absent on .register/.list.
format: date-time

Example

One-time prep (each example is assumed to be complete):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X GET https://api.infrai.cc/v1/account/webhooks/get/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

2.23account.webhooks.update

PATCH /v1/account/webhooks/update/{id}

Partially update the Webhook, modifying the URL will re-trigger SSRF verification.

Parameters

NameTypeRequiredDescription
webhook_idstring
Required
Webhook ID。
urlstringOptionalNew public https address.
format: uri
events("account.created" | "account.updated" | "account.absorbed" | "account.device_linked" | "account.deleted" | "topup.succeeded" | "topup.failed" | "topup.review_started" | "autorecharge.charged" | "autorecharge.failed" | "subscription.activated" | "subscription.renewed" | "subscription.cancelled" | "kyc.status_changed" | "tier.upgraded" | "tier.downgraded" | "wallet.low_balance" | "wallet.expiring_soon" | "wallet.expired" | "email.queued" | "email.sent" | "email.delivered" | "email.opened" | "email.clicked" | "email.bounced" | "email.complained" | "email.deferred" | "email.cancelled" | "email.unsubscribed" | "email.auto_suppressed" | "sms.queued" | "sms.sent" | "sms.delivered" | "sms.failed" | "sms.inbound" | "image.job.completed" | "image.job.failed" | "video.job.completed" | "video.job.failed" | "ai.batch.completed" | "ai.batch.failed" | "captcha.verified" | "captcha.failed" | "realtime.channel.occupied" | "realtime.channel.vacated" | "realtime.member.added" | "realtime.member.removed" | "cron.executed" | "cron.failed" | "cron.missed" | "queue.dlq" | "observability.alert.fired" | "error.captured" | "error.rate_anomaly" | "system.vendor.down" | "system.maintenance.scheduled")[] | nullOptionalList of new subscription event types.
≥ 1 item
descriptionstringOptionalNotes.
≤ 256 chars
activebooleanOptionalWhether to enable this webhook.
retry_policy"default" | "aggressive" | nullOptionalRetry policy: default or aggressive.
headersRecord<string, string>OptionalAdditional custom HTTP headers for each delivery.
idempotency_keystringOptionalOptional dedup key; identical retries return the same result.

Returns

Webhook { id, url, events, active, retry_policy }
NameTypeDescription
webhook_idstringWebhook subscription id (whk_… in the account_resource store).
pattern: ^whk?_[A-Za-z0-9]{16,}$
urlstringURL for this resource or endpoint
format: uri
eventsstring[]Event names per enums/webhook_event.yaml.
descriptionstring | nullFree-text description of this resource
secretstring | nullPlaintext secret — returned only on initial create.
secret_hashstring | nullSHA-256 hex of secret; returned on list/get.
activebooleanWhether deliveries are sent. Canonical state field.
enabledboolean | nullBack-compat alias of `active` (console reads this).
statusstring | nullaccount_resource lifecycle status (e.g. 'active').
retry_policy"default" | "aggressive" | nullRetry policy configuration
headersobject | nullCustom HTTP headers added to every delivery.
last_delivery_atstring | nullISO 8601 timestamp of the last delivery attempt
format: date-time
last_delivery_status"success" | "failed" | nullStatus of the last delivery attempt
failure_count_24hintegerNumber of failed deliveries in the last 24 hours
≥ 0
auto_disabled_atstring | nullSet when 100 consecutive failures triggered auto-disable.
format: date-time
created_atstring | nullISO 8601 timestamp when this resource was created
format: date-time
updated_atstring | nullISO 8601 timestamp when this resource was last updated. Returned by .get/.update; absent on .register/.list.
format: date-time

Example

One-time prep (each example is assumed to be complete):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X PATCH https://api.infrai.cc/v1/account/webhooks/update/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

2.24account.webhooks.delete

DELETE /v1/account/webhooks/delete/{id}

Delete webhook.

Parameters

NameTypeRequiredDescription
webhook_idstring
Required
Webhook ID。
idempotency_keystringOptionalOptional dedup key; identical retries return the same result.

Returns

{ deleted: boolean }
NameTypeDescription
webhook_idstringThe webhook id that was targeted for deletion.
deletedbooleanWhether a webhook was actually deleted (false when webhook_id didn't resolve to a row on this account).

Example

One-time prep (each example is assumed to be complete):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X DELETE https://api.infrai.cc/v1/account/webhooks/delete/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

2.25account.webhooks.test

POST /v1/account/webhooks/test/{id}

Send a test event to the webhook to verify connectivity.

Parameters

NameTypeRequiredDescription
webhook_idstring
Required
Webhook ID。

Returns

WebhookDelivery { delivery_id, status_code, ok }
NameTypeDescription
webhook_idstringUnique identifier for this webhook
pattern: ^whk_[A-Za-z0-9]{20,}$
eventstringEvent name fired in the test (e.g. 'topup.succeeded').
deliveredbooleanWhether the webhook delivery succeeded
http_statusinteger | nullHTTP status code of the webhook delivery attempt
100–599
latency_msinteger | nullLatency of the operation in milliseconds
≥ 0
errorstring | nullError message if the operation failed
delivery_idstring | nullUnique identifier for this delivery attempt
pattern: ^dlv_[A-Za-z0-9]{20,}$
tested_atstringISO 8601 timestamp when the test was executed
format: date-time

Example

One-time prep (each example is assumed to be complete):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X POST https://api.infrai.cc/v1/account/webhooks/test/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

2.26account.webhooks.deliveries

GET /v1/account/webhooks/deliveries/{id}

List the delivery records of a certain webhook in pages.

Parameters

NameTypeRequiredDescription
webhook_idstring
Required
Webhook ID。
cursorstringOptionalPaging cursor: Pass in the next_cursor returned from the previous page to get the next page.
limitnumberOptionalThe maximum number of items returned on a single page.

Returns

{ items: Array<WebhookDelivery>, next_cursor? }
NameTypeDescription
itemsobject[]Array of result items in this page
items[].delivery_idstringUnique identifier for this delivery attempt
pattern: ^dlv_[A-Za-z0-9]{20,}$
items[].webhook_idstringUnique identifier for this webhook
pattern: ^whk_[A-Za-z0-9]{20,}$
items[].eventstringEvent name per enums/webhook_event.yaml.
items[].status"pending" | "success" | "retry" | "failed" | "dlq"Current status of this resource
items[].attemptintegerCurrent attempt number (for retries)
≥ 1
items[].http_statusinteger | nullHTTP status code of the webhook delivery attempt
100–599
items[].latency_msinteger | nullLatency of the operation in milliseconds
≥ 0
items[].response_body_truncatedstring | nullTruncated response body from the webhook delivery attempt
≤ 4096 chars
items[].errorstring | nullError message if the operation failed
items[].created_atstringISO 8601 timestamp when this resource was created
format: date-time
items[].completed_atstring | nullISO 8601 timestamp when execution completed
format: date-time
next_cursorstring | nullOpaque cursor to fetch the next page; null/absent if this is the last page
countintegerTotal number of items across all pages
≥ 0

Example

One-time prep (each example is assumed to be complete):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X GET https://api.infrai.cc/v1/account/webhooks/deliveries/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

2.27account.routing.get

GET /v1/account/routing/get

Get account-level routing configuration (link coverage, failover policy, fixed vendors).

Returns

RoutingConfig { chain_override?, failover_policy, pinned_vendors }
NameTypeDescription
preferencesobjectaccount.routing.get only. Per-capability vendor exclude list the account has configured, keyed by capability id.
effective_chainsobjectaccount.routing.get only. Per-capability failover chain after applying the account's exclude and filtering to currently-usable vendors, keyed by capability id. Each entry is model-first: the vendor plus the model it serves.
no_china_routebooleanaccount.routing.get (current value) / account.routing.set (echoed new value, only when the no_china_route toggle was set). Data-sovereignty flag: when true the gateway routes only to non-China vendors.
capabilitystringaccount.routing.set only (per-capability exclude sub-action). The capability the exclude list was set for.
excludestring[]account.routing.set only (per-capability exclude sub-action). Echo of the vendor ids excluded from that capability's chain.
okbooleanaccount.routing.set only. Always true — confirms the write was applied.

Example

One-time prep (each example is assumed to be complete):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X GET https://api.infrai.cc/v1/account/routing/get \
  -H "Authorization: Bearer $INFRAI_API_KEY"

2.28account.routing.set

PUT /v1/account/routing/set

Set account-level routing: override the default manufacturer link and fix the specified manufacturer.

Parameters

NameTypeRequiredDescription
chain_overridestring[]OptionalVendor priority link coverage list.
pinned_vendorsstring[]OptionalFixed list of manufacturers.

Returns

RoutingConfig { chain_override?, failover_policy, pinned_vendors }
NameTypeDescription
preferencesobjectaccount.routing.get only. Per-capability vendor exclude list the account has configured, keyed by capability id.
effective_chainsobjectaccount.routing.get only. Per-capability failover chain after applying the account's exclude and filtering to currently-usable vendors, keyed by capability id. Each entry is model-first: the vendor plus the model it serves.
no_china_routebooleanaccount.routing.get (current value) / account.routing.set (echoed new value, only when the no_china_route toggle was set). Data-sovereignty flag: when true the gateway routes only to non-China vendors.
capabilitystringaccount.routing.set only (per-capability exclude sub-action). The capability the exclude list was set for.
excludestring[]account.routing.set only (per-capability exclude sub-action). Echo of the vendor ids excluded from that capability's chain.
okbooleanaccount.routing.set only. Always true — confirms the write was applied.

Example

One-time prep (each example is assumed to be complete):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X PUT https://api.infrai.cc/v1/account/routing/set \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"capability": "ai.chat"}'

2.29account.routing.test

POST /v1/account/routing/test

Test route resolution: Given the capability, the manufacturer link to be selected is returned.

Parameters

NameTypeRequiredDescription
capabilitystring
Required
The capability ID to test (such as ai.chat).
default: "ai.chat"e.g. ai.chat
chain_overridestring[]OptionalTemporary link coverage used for this test.

Returns

RoutingTestResult { ok, resolved_vendor, resolved_model?, tested_at? }
NameTypeDescription
capabilitystringThe capability that was tested (defaults to ai.chat if not given).
customizablebooleanWhether this capability accepts a per-account vendor exclude (AI-inference/stateless only).
chainstring[]The effective vendor id chain after applying the account's exclude and filtering to currently-usable vendors.
resultsobject[]Per-vendor reachability, one entry per vendor in `chain`.
results[].vendorstring-
results[].modelstring | nullThe model this vendor would serve for the capability, best-effort.
results[].upbooleanWhether the vendor is currently marked up in the live registry.
okbooleanWhether the test routing resolved successfully

Example

One-time prep (each example is assumed to be complete):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X POST https://api.infrai.cc/v1/account/routing/test \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

3. All capabilities

Every routed capability in this module — the complete public REST contract. The methods above are the guided walkthrough; this index is the full reference.

account.autorecharge.configurePUT /v1/account/autorecharge/configure

Configure automatic balance top-up when funds fall below a trigger threshold, with anti-abuse caps.

Parameters (6)
NameTypeRequiredDescription
trigger_balancenumberRequiredAuto-charge fires when wallet balance drops below this.
≥ 0
recharge_amountnumberRequiredAmount in USD to add each time auto-charge fires.
> 0
payment_method_idstring | nullOptionalnull uses the account default payment method.
max_per_dayintegerOptionalMaximum recharge amount per day in USD
≥ 1default: 3
max_per_monthintegerOptionalMaximum recharge amount per month in USD
≥ 1default: 30
idempotency_keystring | nullOptionalClient-provided idempotency key; prevents duplicate execution on retry
account.autorecharge.getGET /v1/account/autorecharge/get

Get the current auto-recharge configuration.

No request parameters.

account.balanceGET /v1/account/balance

Get the account wallet balance and trial status.

No request parameters.

account.budget.getGET /v1/account/budget/get

Get the budget configuration (period, hard cap, alert thresholds).

No request parameters.

account.budget.setPUT /v1/account/budget/set

Set a hard budget cap and alert thresholds, blocking billable calls when exceeded.

Parameters (4)
NameTypeRequiredDescription
hard_cap_usdnumber | nullRequiredSpending hard cap in USD for the selected period; null removes the cap.
≥ 0
period"daily" | "monthly"RequiredBilling or retention period (e.g. monthly, daily)
alert_threshold_usdnumber | nullOptionalBudget-near alert threshold in USD; null disables the alert.
≥ 0
idempotency_keystring | nullOptionalClient-provided idempotency key; prevents duplicate execution on retry
account.keys.createPOST /v1/account/keys/create

Create an API key; the secret is returned only once.

Parameters (4)
NameTypeRequiredDescription
project_idstring | nullOptionalnull = caller's current project.
namestring | nullOptionalHuman-readable name for this resource
≤ 128 chars
scopesstring[] | nullOptionalEmpty/null = all-modules; explicit scopes per enums/key_scope.yaml.
idempotency_keystring | nullOptionalClient-provided idempotency key; prevents duplicate execution on retry
account.keys.listGET /v1/account/keys/list

List all API keys on the account and their status.

No request parameters.

account.keys.revokeDELETE /v1/account/keys/revoke/{id}

Revoke an API key, taking effect immediately.

Parameters (1)
NameTypeRequiredDescription
idstringRequiredPath parameter.
account.keys.rotatePOST /v1/account/keys/rotate/{id}

Rotate an API key; the old secret stays valid during a grace period.

Parameters (3)
NameTypeRequiredDescription
idstringRequiredPath parameter.
grace_hoursintegerOptionalHours the old key remains valid after rotation
0–168default: 24
idempotency_keystring | nullOptionalClient-provided idempotency key; prevents duplicate execution on retry
account.keys.suspected_compromisePOST /v1/account/keys/suspected_compromise/{id}

Report an API key as suspected compromised to immediately revoke and auto-reissue it.

Parameters (4)
NameTypeRequiredDescription
idstringRequiredPath parameter.
confirmed_leakbooleanOptionalWhether the key leak has been confirmed
default: false
auto_rotatebooleanOptionalWhether to automatically rotate the compromised key
default: true
idempotency_keystring | nullOptionalClient-provided idempotency key; prevents duplicate execution on retry
account.keys.updatePATCH /v1/account/keys/update/{id}

Update an API key's name or scopes; scope tightening takes effect immediately.

Parameters (4)
NameTypeRequiredDescription
idstringRequiredPath parameter.
namestring | nullOptionalHuman-readable name for this resource
≤ 128 chars
scopesstring[] | nullOptionalPermission scopes granted to this API key
idempotency_keystring | nullOptionalClient-provided idempotency key; prevents duplicate execution on retry
account.payment_method.set_defaultPOST /v1/account/payment_method/set_default

Set a payment method as the account default.

Parameters (2)
NameTypeRequiredDescription
payment_method_idstringRequiredIdentifier of the payment method used
idempotency_keystring | nullOptionalClient-provided idempotency key; prevents duplicate execution on retry
account.routing.getGET /v1/account/routing/get

Get the account's AI routing preference: per-capability vendor chains (model-annotated) + excluded vendors.

No request parameters.

account.routing.setPUT /v1/account/routing/set

Exclude vendors from an AI capability's routing (cost / reliability / data sovereignty).

Parameters (3)
NameTypeRequiredDescription
capabilitystringRequiredAI-inference capability id (ai.*) whose vendor exclude is being set.
e.g. ai.chat
excludestring[]OptionalVendors to never route this capability to (cost / reliability / data sovereignty).
default: []e.g. ["openai"]
idempotency_keystring | nullOptionalClient-provided idempotency key; prevents duplicate execution on retry
account.routing.testPOST /v1/account/routing/test

Test routing resolution for an AI capability: the vendor chain and the model each serves.

Parameters (1)
NameTypeRequiredDescription
capabilitystring | nullOptionalCapability id whose routing chain to test (defaults to ai.chat).
default: "ai.chat"e.g. ai.chat
account.subscription.getGET /v1/account/subscription/get

Get the subscription status and billing period.

No request parameters.

account.tierGET /v1/account/tier

Get the current tier and its quota limits.

No request parameters.

account.tier.upgradePOST /v1/account/tier/upgrade

Upgrade the account tier (pro/team/enterprise), returning a checkout URL when payment is required.

Parameters (3)
NameTypeRequiredDescription
target"pro" | "team" | "enterprise"RequiredTarget URL or resource for webhook or notification
return_urlstring | nullOptionalWhere checkout redirects after success/cancel; echoed into the hosted checkout session.
format: uri
idempotency_keystring | nullOptionalClient-provided idempotency key; prevents duplicate execution on retry
account.topupPOST /v1/account/topup

Create a Stripe top-up session and return the hosted payment page URL.

Parameters (5)
NameTypeRequiredDescription
amount_usdnumber | nullOptionalTop-up amount in USD.
≥ 0
amountnumber | nullOptionalLegacy alias for amount_usd.
≥ 0
currencystringOptionalISO 4217 currency code (e.g. USD, CNY)
default: "USD"
return_urlstring | nullOptionalURL the checkout redirects back to; defaults to the configured return URL.
format: uri
idempotency_keystring | nullOptionalClient-provided idempotency key; prevents duplicate execution on retry
account.topup.statusGET /v1/account/topup/status

Get the pending, paid, failed, or unknown status of a top-up session.

Parameters (1)
NameTypeRequiredDescription
topup_idstringOptionalTop-up session id returned by account.topup.
account.usageGET /v1/account/usage

Summarize usage for the current billing period: spend, request count, and a per-capability breakdown.

No request parameters.

account.usage.timeseriesGET /v1/account/usage/timeseries

Return a usage time series at hour, day, or month granularity.

No request parameters.

account.webhooks.deleteDELETE /v1/account/webhooks/delete/{id}

Delete a webhook registration; no further event deliveries are sent to its URL. Idempotent.

Parameters (1)
NameTypeRequiredDescription
idstringRequiredPath parameter.
account.webhooks.deliveriesGET /v1/account/webhooks/deliveries/{id}

List a webhook's delivery records with pagination.

Parameters (1)
NameTypeRequiredDescription
idstringRequiredPath parameter.
account.webhooks.getGET /v1/account/webhooks/get/{id}

Get details for a single webhook.

Parameters (1)
NameTypeRequiredDescription
idstringRequiredPath parameter.
account.webhooks.listGET /v1/account/webhooks/list

List registered webhooks with pagination.

No request parameters.

account.webhooks.registerPOST /v1/account/webhooks/register

Register a webhook (public HTTPS, SSRF-validated); the signing secret is returned only once.

Parameters (7)
NameTypeRequiredDescription
urlstringRequiredURL for this resource or endpoint
format: uri
events("account.created" | "account.updated" | "account.absorbed" | "account.device_linked" | "account.deleted" | "topup.succeeded" | "topup.failed" | "topup.review_started" | "autorecharge.charged" | "autorecharge.failed" | "subscription.activated" | "subscription.renewed" | "subscription.cancelled" | "kyc.status_changed" | "tier.upgraded" | "tier.downgraded" | "wallet.low_balance" | "wallet.expiring_soon" | "wallet.expired" | "email.queued" | "email.sent" | "email.delivered" | "email.opened" | "email.clicked" | "email.bounced" | "email.complained" | "email.deferred" | "email.cancelled" | "email.unsubscribed" | "email.auto_suppressed" | "sms.queued" | "sms.sent" | "sms.delivered" | "sms.failed" | "sms.inbound" | "image.job.completed" | "image.job.failed" | "video.job.completed" | "video.job.failed" | "ai.batch.completed" | "ai.batch.failed" | "captcha.verified" | "captcha.failed" | "realtime.channel.occupied" | "realtime.channel.vacated" | "realtime.member.added" | "realtime.member.removed" | "cron.executed" | "cron.failed" | "cron.missed" | "queue.dlq" | "observability.alert.fired" | "error.captured" | "error.rate_anomaly" | "system.vendor.down" | "system.maintenance.scheduled")[]RequiredEvent types to subscribe this webhook to; the closed set is the global event catalog.
≥ 1 item
descriptionstring | nullOptionalFree-text description of this resource
≤ 256 chars
secretstring | nullOptionalOptional caller-provided signing secret; auto-generated when null.
retry_policy"default" | "aggressive" | nullOptionalRetry policy configuration
headersobject | nullOptionalCustom HTTP headers added to every delivery.
idempotency_keystring | nullOptionalClient-provided idempotency key; prevents duplicate execution on retry
account.webhooks.testPOST /v1/account/webhooks/test/{id}

Send a test event to a webhook to verify connectivity.

Parameters (1)
NameTypeRequiredDescription
idstringRequiredPath parameter.
account.webhooks.updatePATCH /v1/account/webhooks/update/{id}

Partially update a webhook; changing the URL re-runs SSRF validation.

Parameters (8)
NameTypeRequiredDescription
idstringRequiredPath parameter.
urlstring | nullOptionalURL for this resource or endpoint
format: uri
events("account.created" | "account.updated" | "account.absorbed" | "account.device_linked" | "account.deleted" | "topup.succeeded" | "topup.failed" | "topup.review_started" | "autorecharge.charged" | "autorecharge.failed" | "subscription.activated" | "subscription.renewed" | "subscription.cancelled" | "kyc.status_changed" | "tier.upgraded" | "tier.downgraded" | "wallet.low_balance" | "wallet.expiring_soon" | "wallet.expired" | "email.queued" | "email.sent" | "email.delivered" | "email.opened" | "email.clicked" | "email.bounced" | "email.complained" | "email.deferred" | "email.cancelled" | "email.unsubscribed" | "email.auto_suppressed" | "sms.queued" | "sms.sent" | "sms.delivered" | "sms.failed" | "sms.inbound" | "image.job.completed" | "image.job.failed" | "video.job.completed" | "video.job.failed" | "ai.batch.completed" | "ai.batch.failed" | "captcha.verified" | "captcha.failed" | "realtime.channel.occupied" | "realtime.channel.vacated" | "realtime.member.added" | "realtime.member.removed" | "cron.executed" | "cron.failed" | "cron.missed" | "queue.dlq" | "observability.alert.fired" | "error.captured" | "error.rate_anomaly" | "system.vendor.down" | "system.maintenance.scheduled")[] | nullOptionalList of event types this subscription listens to
≥ 1 item
descriptionstring | nullOptionalFree-text description of this resource
≤ 256 chars
activeboolean | nullOptionalWhether this resource is currently active
retry_policy"default" | "aggressive" | nullOptionalRetry policy configuration
headersobject | nullOptionalCustom HTTP headers to include in requests or responses
idempotency_keystring | nullOptionalClient-provided idempotency key; prevents duplicate execution on retry
account.whoamiGET /v1/account/whoami

Get an account summary (ID, type, status, tier, balance).

No request parameters.

4. End-to-end example

A production-style walkthrough of this module: configure once, then run the flow. It exercises most of the module's APIs.

A copy-paste-runnable single-file Python program (stdlib only, no SDK): set your INFRAI_API_KEY, run it, and walk this module's core flow with REAL billed calls — later steps reuse real fields returned by earlier ones. The 12-line helper is the entire integration.

python
#!/usr/bin/env python3
"""Infrai · account — runnable real-app example (single file, zero deps).

Copy this file, set your key, run it: every step is a REAL call to
api.infrai.cc, billed at the real (tiny) per-call price, printing the
live JSON response. Get a key at https://infrai.cc/login (Google/
GitHub sign-in grants $2 free credit); add funds at
https://infrai.cc/billing. No SDK — the 12-line helper below is the
entire integration."""
import json
import os
from urllib import error, request

KEY = os.environ.get("INFRAI_API_KEY") or "ifr_..."  # <- your key
BASE = "https://api.infrai.cc"


# Same raw HTTPS POST/GET as every per-method example on this page —
# wrapped once for reuse. There is nothing else to it: no SDK.
def infrai(method, path, body=None):
    req = request.Request(
        BASE + path, method=method,
        data=json.dumps(body).encode() if body is not None else None,
        headers={"Authorization": f"Bearer {KEY}",
                 "Content-Type": "application/json"})
    try:
        with request.urlopen(req, timeout=60) as r:
            return json.loads(r.read())
    except error.HTTPError as e:
        return json.loads(e.read())


def show(label, resp):
    print(f"\n== {label} ==")
    print(json.dumps(resp, indent=2, ensure_ascii=False))
    return resp


# 1) account.whoami — GET /v1/account/whoami · Get an account summary (ID, type, status, tier, balance).
r1 = show("account.whoami", infrai("GET", "/v1/account/whoami"))

# 2) account.balance — GET /v1/account/balance · Get the account wallet balance and trial status.
r2 = show("account.balance", infrai("GET", "/v1/account/balance"))

# 3) account.usage — GET /v1/account/usage · Summarize usage for the current billing period: spend, request count, and a per-capability breakdown.
r3 = show("account.usage", infrai("GET", "/v1/account/usage"))

5. Developer guides

Move from endpoint details to complete workflows, production patterns and troubleshooting guides verified against the live API.

Account developer guides