Admin

Grant a user credit

Writes one line to the account's credit ledger and answers with the balance it produced. Needs the admin role. The ledger is append-only and the balance is its sum — there is no balance to set and no line to edit or delete. A mistake is corrected by writing a negative amount_usd, which leaves the wrong line on the record beside the one that compensates for it. kind is required. Money received and credit given away report differently — one is revenue, the other customer-acquisition cost — so the line says which it is rather than defaulting to one of them. The balance this moves is not yet a ceiling anything enforces; turning it into one is a separate mechanism.

post/v1/admin/users/{user_id}/credits

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/admin/users/{user_id}/credits
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.naturali.ai/authorize, token URL https://api.naturali.ai/token, scopes: mcp:access)

Path parameters

user_idstring required

Request body

kind'purchased' | 'granted' | 'earned' required

What this line is. purchased for money that arrived, granted for credit naturali gave away — the two report differently, so it is required rather than defaulted. earned writes a withdrawal or a dispute against marketplace earnings and requires reason; a negative one is refused while the account's balance is negative. included is not accepted here: a plan's monthly allowance is the billing cycle's to write.

amount_usdnumber required

US dollars to grant, rounded to the cent. Negative corrects an earlier grant; zero is refused, because a grant of nothing records no intent.

reasonstring nullable

Why, for the record. Required for earned.

Example request

{
  "kind": "purchased",
  "amount_usd": 25,
  "reason": "design partner"
}

Response

The line that was written, and the balance after it.

credit_balance_usdnumber required

The balance after the line was written.

Example response

{
  "entry": {
    "id": "cre_V1StGXR8Z5jdHi6B",
    "kind": "granted",
    "amount_usd": 25,
    "reason": "design partner",
    "project_id": "proj_V1StGXR8Z5jdHi6B",
    "granted_by_user_id": "user_V1StGXR8Z5jdHi6B",
    "created_at": "2026-09-02T00:00:00.000Z"
  },
  "credit_balance_usd": 25
}

Changes

No recorded changes to this operation across all 1 revision of this API.