> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ringg.ai/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> To search or read these docs, connect the Ringg docs MCP server at https://docs.ringg.ai/mcp (no key needed; tools search_ringg_ai and query_docs_filesystem_ringg_ai) instead of browsing pages one by one. Setup for each client: https://docs.ringg.ai/resources/mcp-server/docs-mcp-server/mcp-for-ai-assistants.md
> The dashboard labels agents "Assistants"; these docs say "agent". Both mean the same object, identified by agent_id.
> API base URL: https://prod-api.ringg.ai/ca/api/v0. Send the workspace API key in the X-API-KEY header, from server-side code only.
> Placing a call dials a real phone number and spends credits. Confirm the number with the user before calling.
> To act on a Ringg workspace (place calls, edit agents, read transcripts), use the separate Ringg workspace MCP server at https://mcp.ringg.ai/mcp: https://docs.ringg.ai/resources/mcp-server/workspace-mcp-server/overview.md
> Set every Ringg Space's wallet to an absolute balance, moving the difference to or from the primary, for prepaid families in individual billing mode.
# Reallocate Credit Balances
export const RelatedTopics = ({items}) =>
;
Use it to distribute a top-up made on the primary across clients or teams, or to pull unused balance back from one Ringg Space to fund another.
## Rules
* The net amount moving out of the primary's pot cannot exceed what the pot holds. Top up on the primary first, then allocate.
* A Ringg Space with a `0` balance cannot place calls; Ringg Spaces have no overdraft.
* Every move is recorded in the workspace ledgers as a transfer, never as a charge.
* In a common-billing family the wallet is shared on the primary and Ringg Spaces hold nothing, so this endpoint returns `400`. Allocate [concurrency](/api-reference/account/ringg-spaces/allocate-concurrency) instead.
## Notes
* Read the current wallets and `family.available_pot` from [Get Ringg Spaces](/api-reference/account/ringg-spaces/get-sub-workspaces) first, then send the full map.
* Amounts in the request can be JSON numbers (`200000`) or numeric strings (`"200000.00"`); they are rounded to two decimals.
* Amounts in the response are decimal strings (`"5000.00"`), unlike the read endpoints.
## Errors
* `400`: `Balance allocation applies to prepaid families only.`
* `400`: `This family uses a shared balance; per-sub wallets do not exist.`
* `400`: `allocations name workspaces that are not active sub-workspaces of this family: [...]`
* `400`: `allocations must cover every active sub-workspace; missing: [...]`
* `400`: `These allocations need 9000.00 from the primary's pot, which only holds 4000.00. Lower the allocations or add balance to the primary workspace first.`
* `401`: Invalid or missing API key.
* `403`: `Sub-workspaces are not enabled for this workspace.` — Ringg Spaces are not enabled on the primary, or the key belongs to a Ringg Space.
* `404`: `Workspace is not a sub-workspace family parent.` — the primary has no Ringg Spaces yet.
* `422`: Empty map, negative value, or a key that is not a UUID.
## OpenAPI
````yaml patch /workspace/sub/credit-balances
openapi: 3.0.0
info:
title: Ringg AI API Documentation
description: >-
The Ringg AI REST API. Base URL https://prod-api.ringg.ai/ca/api/v0; send
your workspace API key in the X-API-KEY header from server-side code only.
Requests and responses are JSON.
version: 2.0.0
contact:
name: Ringg AI support
email: admin@ringg.ai
url: https://docs.ringg.ai
servers:
- url: https://prod-api.ringg.ai/ca/api/v0
security: []
tags:
- name: workspace
description: Endpoints for managing your workspace.
- name: agent
description: Endpoints for managing agents.
- name: calling
description: Endpoints for making and managing calls.
- name: campaign
description: Endpoints for managing campaigns.
- name: analytics
description: Endpoints for accessing call analytics and performance metrics.
- name: termination
description: Endpoints for terminating active calls using different methods.
- name: knowledgebase
description: Endpoints for managing knowledge bases.
paths:
/workspace/sub/credit-balances:
patch:
tags:
- workspace
summary: Reallocate Credit Balances
description: >-
Prepaid, individual-billing families only. Sets every active Ringg
Space's wallet to an absolute balance; the net difference moves from or
to the primary's unallocated pot, which must be able to cover it. Top up
on the primary first, then allocate. Not applicable to common-billing
families, where the wallet is shared on the primary.
operationId: reallocateSubWorkspaceCreditBalances
parameters:
- name: X-API-KEY
in: header
description: >-
(Required) The API key of the PRIMARY workspace. A Ringg Space's own
key is refused (403, or 400 if Ringg Spaces are enabled on it).
required: true
schema:
type: string
example: rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- allocations
properties:
allocations:
type: object
description: >-
(Required) sub_workspace_id -> the Ringg Space's NEW
absolute balance (not a delta). Must include every active
Ringg Space exactly once. Values >= 0, two decimals. Values
may be JSON numbers (`200000`) or numeric strings
(`"200000.00"`).
additionalProperties:
oneOf:
- type: number
- type: string
example:
allocations:
00000000-0000-4000-8000-000000000101: 5000
00000000-0000-4000-8000-000000000114: 3000
responses:
'200':
description: >-
Successful Response: The applied balances. Amounts are decimal
strings.
content:
application/json:
schema:
type: object
properties:
parent_workspace_id:
type: string
example: 00000000-0000-4000-8000-000000000107
parent_available_balance:
type: string
description: >-
The primary's unallocated pot after the move, as a decimal
string.
example: '12000.00'
allocations:
type: object
additionalProperties:
type: string
example:
00000000-0000-4000-8000-000000000101: '5000.00'
00000000-0000-4000-8000-000000000114: '3000.00'
primary:
type: object
properties:
id:
type: string
example: 00000000-0000-4000-8000-000000000107
name:
type: string
example: Acme Collections HQ
example:
parent_workspace_id: 00000000-0000-4000-8000-000000000107
parent_available_balance: '12000.00'
allocations:
00000000-0000-4000-8000-000000000101: '5000.00'
00000000-0000-4000-8000-000000000114: '3000.00'
primary:
id: 00000000-0000-4000-8000-000000000107
name: Acme Collections HQ
'400':
description: >-
Bad Request - Wrong billing mode, an incomplete map, or more than
the primary's pot can cover.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: >-
These allocations need 9000.00 from the primary's pot,
which only holds 4000.00. Lower the allocations or add
balance to the primary workspace first.
'401':
description: Unauthorized - Invalid or missing API key.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Invalid credentials
'403':
description: >-
Forbidden - Ringg Spaces are not enabled for this workspace (also
what a Ringg Space's own key gets), or the caller is not an active
member of the primary.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Sub-workspaces are not enabled for this workspace.
'404':
description: Not Found - The primary has no Ringg Spaces yet.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Workspace is not a sub-workspace family parent.
'500':
description: Internal Server Error - Something went wrong on our end.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: An unexpected error occurred. Please try again later.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.