Schemas

Error

object · required

User

id

string · uuid · required

email

string · required

name

string · required

is_admin

boolean · required

is_owner

boolean · required

The initial admin; can't lose the admin role or be suspended.

balance_nano

integer · int64 · required

Balance in nano-USD (1 USD = 1_000_000_000); can be negative.

disabled_at

string | null · date-time · required

Set while the account is suspended.

disabled_reason

string | null · required

last_login_at

string | null · date-time · required

mfa_enabled

boolean · required

email_verified

boolean · required

created_at

string · date-time · required

UserDetail

object · required

object[] · required

Last 30 days in the site time zone; only days with requests.

object[] · required

Top 10 models of the last 30 days by cost.

UserTopup

order_id

string · required

amount_idr

integer · int64 · required

credit_nano

integer · int64 · required

Credit granted, nano-USD.

status

TopupStatus · enum · required

Enum values:

pending

completed

failed

expired

environment

PaymentEnv · enum · required

Enum values:

sandbox

live

paid_at

string | null · date-time · required

created_at

string · date-time · required

BalanceEntry

kind

string · enum · required

initial is the starting balance set when an admin created the user; usage is one row per day.

Enum values:

topup

coupon

affiliate_commission

affiliate_bonus

admin_credit

initial

usage

amount_nano

integer · int64 · required

Signed change in nano-USD; deductions are negative.

reference

string | null · required

Order id, coupon code, referred user's email (commission), the admin's note, or the day's request count (usage).

actor_email

string | null · required

The admin who made the change (admin_credit, initial).

created_at

string · date-time · required

UserKey

id

string · uuid · required

name

string · required

key_prefix

string · required

Masked display form, e.g. sk-****-a1b2.

credit_limit_nano

integer | null · int64 · required

Spending limit in nano-USD; null for none.

usage_nano

integer · int64 · required

Spend so far, nano-USD.

allowed_models

array | null · required

expires_at

string | null · date-time · required

allowed_ips

array | null · required

redact_secrets

boolean · required

last_used_at

string | null · date-time · required

revoked_at

string | null · date-time · required

created_at

string · date-time · required

UserRequest

id

string · uuid · required

model_slug

string · required

api_key_name

string | null · required

null for playground requests or deleted keys.

prompt_tokens

integer · required

completion_tokens

integer · required

cost_nano

integer · int64 · required

Billed cost, nano-USD.

latency_ms

integer · required

status_code

integer · required

source

RequestSource · enum · required

Enum values:

api

playground

error_type

string | null · required

created_at

string · date-time · required

VirtualKey

id

string · uuid · required

name

string · required

key_prefix

string · required

user_id

string · uuid · required

email

string · required

Owner email.

user_name

string · required

user_disabled

boolean · required

The owner is suspended (the key doesn't work).

status

string · enum · required

Enum values:

active

expired

revoked

credit_limit_nano

integer | null · int64 · required

Spending limit in nano-USD.

budget_period

string | null · enum · required

How often the credit limit resets; null for a lifetime limit.

Enum values:

daily

weekly

monthly

usage_nano

integer · int64 · required

nano-USD.

allowed_models

array | null · required

allowed_ips

array | null · required

max_parallel

integer | null · required

redact_secrets

boolean · required

expires_at

string | null · date-time · required

last_used_at

string | null · date-time · required

revoked_at

string | null · date-time · required

created_at

string · date-time · required

RequestSource

string · enum

Enum values:

api

playground

RequestLog

id

string · uuid · required

user_id

string · uuid · required

user_email

string · required

model_slug

string · required

provider_slug

string · required

api_key_id

string | null · uuid · required

api_key_name

string | null · required

api_key_prefix

string | null · required

prompt_tokens

integer · required

completion_tokens

integer · required

cached_tokens

integer · required

cost_nano

integer · int64 · required

Billed cost, nano-USD.

latency_ms

integer · required

ttft_ms

integer | null · required

Time to first token.

tps

number | null · required

Output tokens per second after the first token.

status_code

integer · required

streamed

boolean · required

source

RequestSource · enum · required

Enum values:

api

playground

error_type

string | null · required

error_message

string | null · required

First 200 characters; the detail has the full message.

created_at

string · date-time · required

When the request finished.

RequestLogDetail

id

string · uuid · required

user_id

string · uuid · required

user_email

string · required

upstream_id

string | null · required

The provider's response id.

model_slug

string · required

provider_slug

string · required

api_key_id

string | null · uuid · required

api_key_name

string | null · required

api_key_prefix

string | null · required

source

RequestSource · enum · required

Enum values:

api

playground

streamed

boolean · required

status_code

integer · required

finish_reason

string | null · required

prompt_tokens

integer · required

completion_tokens

integer · required

cached_tokens

integer · required

cache_write_tokens

integer · required

reasoning_tokens

integer · required

cost_nano

integer · int64 · required

Billed cost, nano-USD.

upstream_cost_nano

integer | null · int64 · required

What Sumopod charged, nano-USD, when recorded.

cost_breakdown

required

Per-component cost details (JSON), when recorded.

latency_ms

integer · required

ttft_ms

integer | null · required

tps

number | null · required

request_params

required

Request parameters (JSON, e.g. temperature, max_tokens); never prompt content. May be cleared by retention.

error_type

string | null · required

error_message

string | null · required

client_ip

string | null · required

user_agent

string | null · required

started_at

string · date-time · required

created_at minus the latency.

created_at

string · date-time · required

KeyRef

id

string · uuid · required

name

string · required

key_prefix

string · required

user_id

string · uuid · required

user_email

string · required

revoked

boolean · required

LogFilterOptions

models

string[] · required

Model slugs seen in the period.

providers

string[] · required

error_types

string[] · required

object | null · required

The filtered user, if any.

KeyRef[] · required

The filtered user's keys (revoked included); empty without a user filter.

KeyRef | null · required

The filtered key, if any.

AdminModel

id

string · uuid · required

slug

string · required

Model id used in API requests, e.g. anthropic/claude-sonnet-4.5.

name

string · required

description

string · required

owned_by

string · required

context_length

integer · required

prompt_price_nano

integer · int64 · required

Sell price per 1M prompt tokens, nano-USD.

completion_price_nano

integer · int64 · required

Sell price per 1M completion tokens, nano-USD.

cache_read_price_nano

integer | null · int64 · required

Sell price per 1M cached prompt tokens, nano-USD; null bills them at the prompt price.

cost_prompt_price_nano

integer | null · int64 · required

Sumopod cost per 1M prompt tokens, nano-USD.

cost_completion_price_nano

integer | null · int64 · required

Sumopod cost per 1M completion tokens, nano-USD.

cost_cache_read_price_nano

integer | null · int64 · required

Sumopod cost per 1M cached tokens, nano-USD.

is_active

boolean · required

Offered to users.

upstream_available

boolean · required

Still listed by Sumopod.

synced_at

string | null · date-time · required

reasoning

boolean | null · required

Admin override; null = automatic.

vision

boolean | null · required

Admin override; null = automatic.

probed_reasoning

boolean | null · required

Probe result; null = not probed or inconclusive.

probed_vision

boolean | null · required

probed_at

string | null · date-time · required

supports_reasoning

boolean · required

Effective value (override, else automatic).

supports_vision

boolean · required

auto_reasoning

boolean · required

What automatic mode resolves to (probe, else name-based).

auto_vision

boolean · required

mode

string | null · enum · required

Admin override; null = detected.

Enum values:

chat

embedding

decision

auto_mode

string · enum · required

Enum values:

chat

embedding

decision

effective_mode

string · enum · required

Enum values:

chat

embedding

decision

PaymentEnv

string · enum

Enum values:

sandbox

live

TopupStatus

string · enum

Enum values:

pending

completed

failed

expired

ReportPeriod

key

string · enum · required

Enum values:

today

yesterday

week

month

all

from

string | null · date-time · required

null for all.

to

string · date-time · required

topup_idr

integer · int64 · required

Paid top-ups (by paid time).

topup_credit_nano

integer · int64 · required

Credit from paid top-ups, nano-USD.

topups

integer · required

topup_users

integer · required

Distinct users with a paid top-up.

created

integer · required

Top-up requests created in the period.

created_idr

integer · int64 · required

pending

integer · required

Of those created, currently pending.

failed

integer · required

expired

integer · required

coupon_nano

integer · int64 · required

Coupon credit redeemed, nano-USD.

affiliate_nano

integer · int64 · required

Affiliate rewards paid, nano-USD.

admin_credit_nano

integer · int64 · required

Net admin balance changes incl. starting balances, nano-USD (can be negative).

usage_nano

integer · int64 · required

What users were billed for requests, nano-USD.

requests

integer · required

new_users

integer · required

FinanceReport

tz

string · required

env

string | null · enum · required

null when both environments are counted.

Enum values:

live

sandbox

generated_at

string · date-time · required

object · required

ReportPeriod[] · required

In order today, yesterday, week, month, all.

object[] · required

The last 30 days, oldest first, every day present.

object[] · required

Up to 10 largest positive balances.

open_pending

integer · required

Unpaid top-ups right now, whatever their age.

open_pending_idr

integer · int64 · required

Payment

order_id

string · required

user_id

string · uuid · required

email

string | null · required

name

string | null · required

amount_idr

integer · int64 · required

credit_nano

integer · int64 · required

Credit granted when paid, nano-USD.

status

TopupStatus · enum · required

Enum values:

pending

completed

failed

expired

environment

PaymentEnv · enum · required

Enum values:

sandbox

live

payment_id

string | null · required

The gateway's payment id.

paid_at

string | null · date-time · required

created_at

string · date-time · required

PaymentDetail

order_id

string · required

user_id

string · uuid · required

email

string | null · required

name

string | null · required

amount_idr

integer · int64 · required

credit_nano

integer · int64 · required

Credit granted when paid, nano-USD.

status

TopupStatus · enum · required

Enum values:

pending

completed

failed

expired

environment

PaymentEnv · enum · required

Enum values:

sandbox

live

payment_id

string | null · required

The gateway's payment id.

paid_at

string | null · date-time · required

created_at

string · date-time · required

payment_link_url

string | null · required

payment_code

string | null · required

QRIS payload.

create_response

required

The gateway's raw reply when the payment was created (JSON or null; may be cleared by retention).

webhook_payload

required

The last webhook received for this order (JSON or null; may be cleared by retention).

Analytics

bucket

string · enum · required

Enum values:

hour

day

object · required

object[] · required

Up to 100 models by revenue.

object[] · required

Up to 100 users by revenue.

Coupon

id

string · uuid · required

code

string · required

credit_nano

integer · int64 · required

Credit per redemption, nano-USD (1 USD = 1_000_000_000).

max_redemptions

integer | null · required

null = unlimited.

redeemed_count

integer · required

expires_at

string | null · date-time · required

is_active

boolean · required

description

string · required

created_by_email

string | null · required

created_at

string · date-time · required

Affiliate

id

string · uuid · required

email

string · required

referral_code

string | null · required

referrals

integer · required

Sign-ups attributed to this user.

paying_referrals

integer · required

Referrals that earned this user a commission.

commission_nano

integer · int64 · required

Commission earned, nano-USD.

referred_topups_idr

integer · int64 · required

Completed top-ups of referred users, IDR.

AffiliateSettings

enabled

boolean

Default: false

commission_percent

number · min: 0 · max: 50

Share of each paid top-up of a referred user credited to the referrer.

Default: 10

commission_months

integer · min: 1 · max: 120

Commission is paid on top-ups within this many months of the referral.

Default: 12

referee_bonus_percent

number · min: 0 · max: 50

Extra credit for the referred user on their first paid top-up.

Default: 10

AiSettings

base_url

string · required

Sumopod AI base URL (fixed by the server configuration).

api_key_hint

string | null · required

Masked key, e.g. sk-****-a1b2; null when not set.

PaymentCredentialsInput

Secrets for one environment. Omitted, `null` or empty values keep the stored secret.

api_key

string | null · writeOnly

webhook_token

string | null · writeOnly

webhook_signing_secret

string | null · writeOnly

PaymentCredentialsView

base_url

string · required

The gateway URL for this environment (fixed).

webhook_url

string · required

URL to register with Sumopod: <site URL>/api/webhooks/sumopod/<env>.

api_key_hint

string | null · required

Masked; null when not set.

webhook_token_hint

string | null · required

webhook_signing_secret_hint

string | null · required

PaymentSettings

enabled

boolean · required

environment

PaymentEnv · enum · required

Enum values:

sandbox

live

payment_method

string · const · required

Fixed.

Const value: QRIS

idr_per_usd

integer · int64 · required

How many IDR buy 1 USD of credit.

min_topup_idr

integer · int64 · required

max_topup_idr

integer · int64 · required

PaymentCredentialsView · required

AuthSettings

email_password_enabled

boolean · required

registration_enabled

boolean · required

When off, only existing accounts can sign in.

google_enabled

boolean · required

google_client_id

string · required

google_client_secret_hint

string | null · required

Masked; null when not set.

google_redirect_uri

string · required

Redirect URI to register with Google (read-only).

require_email_verification

boolean · required

New email/password sign-ups must confirm their address.

email_ready

boolean · required

SMTP is set up, so verification and reset emails can go out (read-only).

block_disposable_emails

boolean · required

block_email_aliases

boolean · required

Refuse +tag aliases and Gmail dot variants of an existing account.

blocked_email_domains

string[] · required

Extra domains to refuse (subdomains included).

turnstile_enabled

boolean · required

Cloudflare Turnstile on sign-in, sign-up and password reset.

turnstile_site_key

string · required

turnstile_secret_key_hint

string | null · required

Masked; null when not set.

LimitsSettings

key_rpm

integer · min: 1 · max: 1000000

Requests per minute per API key without its own limit; also the playground's.

Default: 60

user_rpm

integer · min: 1 · max: 1000000

Requests per minute per user across all their keys; also the highest per-key limit a user can set.

Default: 300

user_max_parallel

integer · min: 1 · max: 1000000

AI requests in progress at once per user.

Default: 20

RetentionSettings

Days to keep each kind of log; 0 keeps forever.

request_logs_days

integer · min: 0 · max: 3650

Deletes request log rows (usage history, analytics and reports go with them; balances are unaffected).

Default: 0

request_details_days

integer · min: 0 · max: 3650

Clears client IP, user agent, request parameters and error messages, keeping tokens and cost.

Default: 0

audit_logs_days

integer · min: 0 · max: 3650

Deletes audit entries, except admin credit and starting balance entries (balance history).

Default: 0

payment_payloads_days

integer · min: 0 · max: 3650

Clears raw gateway responses and webhook payloads stored on top-ups.

Default: 0

RetentionRunResult

started_at

string | null · date-time · required

finished_at

string | null · date-time · required

skipped

boolean · required

Another instance was already running the cleanup.

request_logs_deleted

integer · required

request_details_cleared

integer · required

audit_logs_deleted

integer · required

payment_payloads_cleared

integer · required

email_tokens_deleted

integer · required

Expired email verification / reset tokens removed.

RetentionView

Days to keep each kind of log; 0 keeps forever.

request_logs_days

integer · min: 0 · max: 3650 · required

Deletes request log rows (usage history, analytics and reports go with them; balances are unaffected).

Default: 0

request_details_days

integer · min: 0 · max: 3650 · required

Clears client IP, user agent, request parameters and error messages, keeping tokens and cost.

Default: 0

audit_logs_days

integer · min: 0 · max: 3650 · required

Deletes audit entries, except admin credit and starting balance entries (balance history).

Default: 0

payment_payloads_days

integer · min: 0 · max: 3650 · required

Clears raw gateway responses and webhook payloads stored on top-ups.

Default: 0

object · required

RetentionRunResult | null · required

The last cleanup run, if any.

BrandingSettings

site_name

string · required

site_url

string · required

Stored value; empty means the server's PUBLIC_URL is used.

default_url

string · required

PUBLIC_URL from the server environment (read-only).

icon_url

string | null · required

Versioned public icon URL (/api/branding/icon?v=N); null uses the built-in logo.

timezone

string · required

IANA time zone for usage dates and charts.

SmtpSecurity

string · enum

Enum values:

starttls

tls

none

starttls (usually port 587), tls (usually 465) or none (local test servers only).

EmailTemplateKey

string · enum

Enum values:

confirm_signup

reset_password

password_changed

two_factor_enabled

two_factor_disabled

topup_success

low_balance

EmailTemplate

key

EmailTemplateKey · enum · required

Enum values:

confirm_signup

reset_password

password_changed

two_factor_enabled

two_factor_disabled

topup_success

low_balance

group

string · enum · required

Enum values:

auth

security

billing

variables

string[] · required

Placeholders: the common ones (SiteName, SiteURL, Email, Name) first, then this email's own.

subject

string · required

body

string · required

HTML.

enabled

boolean · required

optional

boolean · required

Notifications can be turned off; account emails cannot.

customized

boolean · required

Differs from the built-in default.

EmailSettings

provider

string · const · required

Const value: smtp

enabled

boolean · required

sender_email

string · required

sender_name

string · required

smtp_host

string · required

Defaults to smtp.sumopod.com.

smtp_port

integer · required

Defaults to 465.

smtp_username

string · required

smtp_password_hint

string | null · required

•••••••• when a password is stored, else null.

smtp_security

SmtpSecurity · enum · required

starttls (usually port 587), tls (usually 465) or none (local test servers only).

Enum values:

starttls

tls

none

EmailTemplate[] · required

AdminApiKeyInput

name

string · minLength: 1 · maxLength: 100 · required

read_only

boolean

Only GET/HEAD requests allowed.

Default: false

expires_at

string | null · date-time

Must be in the future; null never expires.

allowed_ips

array | null · maxItems: 50

IP addresses or CIDR ranges (e.g. 203.0.113.7, 10.0.0.0/8, 2001:db8::/32); empty or null allows any.

AdminApiKey

id

string · uuid · required

name

string · required

key_prefix

string · required

e.g. sk-admin-****a1b2.

read_only

boolean · required

expires_at

string | null · date-time · required

allowed_ips

array | null · required

last_used_at

string | null · date-time · required

last_used_ip

string | null · required

owner_email

string | null · required

created_at

string · date-time · required

AuditEntry

id

string · uuid · required

actor_id

string | null · uuid · required

actor_email

string | null · required

action

string · required

target_type

string | null · required

target_id

string | null · required

details

object · required

Action-specific details; admin_api_key holds the key id when an admin API key was used.

ip

string | null · required

created_at

string · date-time · required