API reference

Update account settings

Update privileged account-level API settings. Review Diffio API behavior, response fields, setup details, and production workflows.

Update account billing policy settings with an admin-capable API key.

POST/v1/account/settings/updatePermissions: admin, account:write

Endpoint

HTTP request

https://api.diffio.ai/v1/account/settings/update

Use POST with a JSON body.

Permissions

admin, account:write

API keys must be active.

Authentication

Send the API key on every request using one of the supported headers.

Authorization: Bearer <apiKey>
X-Api-Key: <apiKey>
Xi-Api-Key: <apiKey>

Request

Send the billing policy object to store for the account.

Body fields

Field	Type	Required	Description
`billingPolicy`	object	Yes	Billing policy to store on the account.
`billingPolicy.type`	string	Yes	Supported values are customerStripe and internalDiffio.
`billingPolicy.reason`	string	No	Optional reason stored with the policy update.

cURL

curl -X POST "https://api.diffio.ai/v1/account/settings/update" \  -H "Authorization: Bearer $DIFFIO_AGENT_KEY" \  -H "Content-Type: application/json" \  -d '{    "billingPolicy": {      "type": "customerStripe",      "reason": "Use standard Stripe billing"    }  }'

Response

Returns the updated account settings.

Response fields

Field	Type	Required	Description
`account`	object	Yes	Updated account settings object.
`account.userId`	string	Yes	Firebase user id that owns the API account.
`account.billingMode`	string	Yes	Billing mode stored for the account.
`account.billingStatus`	string	Yes	Billing status stored for the account.
`account.billingPolicy`	object	Yes	Updated billing policy.
`account.billingPolicy.type`	string	Yes	Stored billing policy type.
`account.currency`	string	Yes	Account billing currency.
`account.updatedAt`	string	No	Last account update timestamp in ISO 8601 format when available.

Successful response

{  "account": {    "userId": "user_123",    "billingMode": "developerProgressive",    "billingStatus": "active",    "billingPolicy": {      "type": "customerStripe",      "updatedAt": "2026-05-09T12:00:00Z",      "updatedByKeyId": "key_123",      "reason": "Use standard Stripe billing"    },    "currency": "usd",    "updatedAt": "2026-05-09T12:00:00Z"  }}

Return codes

200Success, treated as complete.: Account settings updated.
204Success, treated as empty response.: CORS preflight when method is OPTIONS.
400Bad request, treated as client error.: Invalid JSON body, billingPolicy is required, billingPolicy must be an object, or billingPolicy.type is not supported.
401Unauthorized, treated as auth error.: Missing API key, or invalid API key.
403Forbidden, treated as permission error.: Privileged admin API key required, API key is not active, or missing account:write permission.
405Client error, treated as fix required.: Method is not POST.
500Server error, treated as retryable.: API key missing userId, or failed to update account settings.

Notes

Only admin-capable API keys can call this endpoint.
The endpoint writes an audit log entry for billing policy changes.
Scoped keys cannot use this endpoint even when they include account:write.