Pawsitive Future Pawsitive FutureDeveloper docs

post_allocations

Changes data · you confirm first

Calls POST /api/allocations as the signed-in person · REST reference

Grant an organization a standing voucher budget

Adds CENTS to the organization's ORG_ALLOCATION account, which is what later lets it mint voucher batches without per-batch approval. Additive — it tops the balance up rather than setting it, so there is no way to reduce an allocation through this endpoint; POST /api/allocations/{orgId}/revoke takes unspent allocation back. TWO GATES, NOT ONE. The platform-staff middleware is the outer one; the caller's own bearer token is then forwarded so the DAL evaluates the real actor against execute:GrantOrgAllocationCommand. A platform staffer without that command is refused by the DAL with 403. A refused grant is the CALLER'S problem, not the server's: asking for more than the pool can back, omitting orgId or sending a non-UUID one, naming an organization that is not live or not a DISTRIBUTOR or the platform organization (a service provider is never allocated funds), an unknown currency, or a non-positive amount all answer 400. An organization that does not exist, or is deleted, answers 404. A grant that lost a race with another write to the same allocation answers 409 — retry it. A DAL that does not answer is 503.

Arguments

ArgumentTypeDescription
bodyJSONobjectrequiredThe request body, as a JSON object. Its fields are listed below.

Fields of body

FieldTypeDescription
amountintegerrequiredCENTS to ADD to the org's allocation. Must be a positive integer.
currencystringCurrency of the allocation account. Defaulted by the DAL, not here.
descriptionstringFree text recorded on the resulting ledger transaction.
orgIdstring (uuid)requiredOrganization to fund. Not validated here — an omitted, non-UUID or non-live org is refused by the DAL as a 400; one that does not exist answers 404.

Example call

A client sends this over the MCP session; Claude and other agents build it for you. The values are placeholders — the shape is real.

json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "post_allocations",
    "arguments": {
      "body": {
        "amount": 1,
        "orgId": "11111111-1111-4111-8111-111111111111",
        "currency": "USD",
        "description": "string"
      }
    }
  }
}
Confirmation
The client shows the person the exact request and waits. Nothing runs until they tick Make this change. See Reading and changing.

Result

On success (HTTP 201) the tool returns one text item holding the API's JSON, pretty-printed.

The allocation was granted, verbatim as the DAL reports it.

json
{
  "accountId": "11111111-1111-4111-8111-111111111111",
  "amount": 1,
  "currency": "string",
  "newBalance": 1,
  "orgId": "11111111-1111-4111-8111-111111111111",
  "transactionId": "11111111-1111-4111-8111-111111111111"
}

Fields

FieldTypeDescription
accountIdstring (uuid)The ORG_ALLOCATION account credited, created on first grant.
amountintegerAmount granted by THIS call, in CENTS.
currencystring
newBalanceintegerThe org's allocation balance after the grant, in CENTS.
orgIdstring (uuid)
transactionIdstring (uuid)Ledger transaction recording the grant.

When it fails

A failed call returns isError: true with the API's message as text. A change the person declines, or lets time out, also comes back this way and nothing changes.

400

The request was malformed or failed a guard.

403

Authenticated, but the caller holds none of the required permissions.

404

No such resource — or none this caller may see.

409

The resource is not in a state that allows this operation.

What the model is shown

This is the tool exactly as the server lists it in tools/list. The description starts with the REST call it makes.

json
{
  "name": "post_allocations",
  "description": "POST /api/allocations — Adds CENTS to the organization's ORG_ALLOCATION account, which is what later lets it mint voucher batches without per-batch approval. Additive — it tops the balance up rather than setting it, so there is no way to reduce an allocation through this endpoint; `POST /api/allocations/{orgId}/revoke` takes unspent allocation back. TWO GATES, NOT ONE. The platform-staff middleware is the outer one; the caller's own bearer token is then forwarded so the DAL evaluates the real actor against `execute:GrantOrgAllocationCommand`. A platform staffer without that command is refused by the DAL with 403. A refused grant is the CALLER'S problem, not the server's: asking for more than the pool can back, omitting `orgId` or sending a non-UUID one, naming an organization that is not live or not a DISTRIBUTOR or the platform organization (a service provider is never allocated funds), an unknown currency, or a non-positive amount all answer 400. An organization that does not exist, or is deleted, answers 404. A grant that lost a race with another write to the same allocation answers 409 — retry it. A DAL that does not answer is 503.\n\nThis changes data. The person is asked to confirm it before it runs, and nothing happens if they decline.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "body": {
        "type": "string",
        "description": "The JSON request body: { amount*: integer (CENTS to ADD to the org's allocation.); currency: string (Currency of the allocation account.); description: string (Free text recorded on the resulting ledger transaction.); orgId*: string (Organization to fund.) }"
      }
    },
    "required": [
      "body"
    ]
  },
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": true,
    "idempotentHint": false,
    "openWorldHint": false
  }
}