Authorization

bearerAuth

AuthorizationBearer <token>

A personal API key (psk_…) or an OAuth access token (plan_at_…). Scopes: read, write.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

fromUserId?|

null moves from the shared pool.

toUserId?|

null moves into the shared pool.

amountMicrocredits?string

A positive integer, as a string. Send exactly one of this or percentOfTransferable.

percentOfTransferable?number

A share of what the source can currently move, above 0 and up to 100, with at most one decimal. It is resolved server-side against the same figure GET /v1/usage reports, so the caller never re-derives it. Send exactly one of this or amountMicrocredits. Quote first and commit the quote's amountMicrocredits: a percentage re-resolves after a partial success.

reason*string

Required; it lands in the audit log.

operationKey*string

Caller-supplied and stable across retries, so a lost response cannot move the usage twice. The two amount shapes replay differently, on purpose: replaying with a different amountMicrocredits is a 409, because a different number is a different transfer. Replaying with percentOfTransferable returns the transfer that key already committed (replay: true), because a percentage re-resolves against a balance the first attempt may already have moved — that is idempotency by INTENT rather than by value. It still requires the same two parties and the same reason; anything else is a 409.

Response Body

`application/json`

curl -X POST "https://example.com/v1/usage/transfer/quote" \  -H "Content-Type: application/json" \  -d '{    "reason": "string",    "operationKey": "string"  }'

{  "quotedAt": "string",  "amountMicrocredits": "string",  "from": {    "userId": "string",    "pctUsedBefore": 0,    "pctUsedAfter": 0,    "balanceBeforeMicrocredits": "string",    "balanceAfterMicrocredits": "string",    "capacityBeforeMicrocredits": "string",    "capacityAfterMicrocredits": "string",    "transferableMicrocredits": "string"  },  "to": {    "userId": "string",    "pctUsedBefore": 0,    "pctUsedAfter": 0,    "balanceBeforeMicrocredits": "string",    "balanceAfterMicrocredits": "string",    "capacityBeforeMicrocredits": "string",    "capacityAfterMicrocredits": "string",    "transferableMicrocredits": "string"  },  "moving": [    {      "kind": "MONTHLY_GRANT",      "microcredits": "string",      "expiresAt": "string"    }  ],  "debtRepaidMicrocredits": "string",  "refusal": {    "code": "string",    "message": "string"  }}

View as Markdown Open in Claude Open in ChatGPT

What moving usage would do, to both people

Authorization

Request Body

Response Body

200application/json

401application/json

404application/json

429application/json

`application/json`

`application/json`

`application/json`

`application/json`