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" \  -H "Content-Type: application/json" \  -d '{    "reason": "string",    "operationKey": "string"  }'

{  "transferId": "string",  "movedMicrocredits": "string",  "debtRepaidMicrocredits": "string",  "replay": true}

View as Markdown Open in Claude Open in ChatGPT

Move usage between people, or to and from the shared pool

Authorization

Request Body

Response Body

200application/json

401application/json

404application/json

409application/json

429application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`