workspace/post_credits_by_id
Tool: create
Allocate sending credits from the main account to a workspace. Only the main account may call this, and only against a workspace with separate credits. Credits are credited to the workspace first, then debited from the main account; a failed main-account debit is reversed on the workspace.
This moves credits one way only. There is no de-allocation operation, and amount must be a positive integer — 0 or a negative value is rejected with 422 Amount must be a positive integer, so credits cannot be pulled back out of a workspace through the API. Allocate what is needed rather than a large round number.
A shared-credit workspace is rejected with 422 naming the workspace: it has no balance of its own. The credit mode is changed in the web app under Workspaces settings — the API cannot change it (workspace/patch_by_id accepts only title), so retrying, or calling another operation first, will not help. Clientspaces differ: there separateCredits is settable, via clientspace/patch_by_id.
externalReferencemakes the call idempotent, and a stuckpendingreplay needs a balance check before you retry. SetexternalReferenceon every automated call. A replay of the same reference returns 200 with the original allocation instead of moving credits again; reusing it with a different workspace or amount is rejected with 422 (one reference identifies exactly one allocation). A blank/whitespace value counts as omitted. A replayedfailedallocation is returned as-is and never re-run — retry with a new reference once the cause is fixed. But a replayedpendingallocation older than 15 minutes is returned asfailedbecause the original request crashed before finishing — and it may have crashed after the credits already moved, so check the balance with workspace/get_credits_by_id before retrying with a new reference, or you risk a double allocation.
Arguments
| name | type | req | notes |
|---|---|---|---|
| id | integer | ✓ | Workspace ID — the object's workspaceId |
Body
| field | type | req | constraints | description |
|---|---|---|---|---|
| amount | integer | ✓ | ≥1 | Sending credits to move from the main account to the workspace |
| note | string | – | ≤256 chars | Free-text note for the allocation; defaults to Added from main account when omitted |
| externalReference | string | – | ≤128 chars | Idempotency key, unique per main account — see the caveat above |
Response
201 — Credits allocated; new allocation object (fields below).
200 — Idempotent replay: externalReference was already used; returns the original allocation unchanged, no credits moved.
| field | type | description |
|---|---|---|
| allocationId | integer | Unique identifier of the allocation. |
| workspaceId | integer | Workspace the credits were allocated to. |
| amount | integer | Credits moved from the main account to the workspace. |
| note | string | The note recorded with the allocation. |
| externalReference | string | The idempotency key it was created with; null when none was given. |
| status | string | pending while in flight, completed once both ledger legs succeeded, failed if the move could not complete. |
| balance | integer | Workspace's sending-credit balance, read after the allocation. |
| mainAccountBalance | integer | Main account's sending-credit balance, read after the allocation. |
| createdAt | string | When the allocation was created. |
Errors: 400, 401, 402 (INSUFFICIENT_SENDING_CREDITS — insufficient credits on the main account), 403, 404, 406, 409, 415, 422, 429, 500 — shared schema: schemas/errors.
Invoke
Call create with name: "workspace/post_credits_by_id".