---
title: "Grant Credits"
method: POST
path: "/admin/workspaces/{slug}/credits"
tags: ["Admin"]
---

# Grant Credits

`POST /admin/workspaces/{slug}/credits`

## Request

- Base URL: `https://api.kolens.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.kolens.ai/admin/workspaces/{slug}/credits`
- Auth: none declared

Set or adjust a workspace's credit balance by hand.

No payment is involved anywhere in this path — no Stripe call, no
checkout, no card. It writes ``workspaces.credits`` directly. The
ledger row it also writes lives in ``workspace_credit_purchases``
only because that is where a workspace's credit history is read
from; its ``stripe_session_id`` column is a historical name being
reused as a unique idempotency key, not a payment reference.

Two modes, because "top up by 500" and "make the balance 500" are
different operations and guessing which one an operator meant is
how a balance ends up wrong:

* ``add`` — ``credits`` is a delta. Negative corrects an over-grant.
* ``set`` — ``credits`` is the balance to end up with. The delta is
  derived, so the ledger and the audit log still record what
  actually moved.

## Path parameters

- `slug` string, required

## Headers

- `x-admin-secret` string, nullable

## Request body

- GrantRequest
  - `mode` string: ``add`` treats ``credits`` as a delta; ``set`` treats it as the balance to end up with.
  - `credits` number, required: In ``add`` mode, credits to add (negative corrects an over-grant). In ``set`` mode, the resulting balance.
  - `reason` string, required: Why. Written to the audit log and the ledger row.
  - `idempotency_key` string, nullable: Same key = same grant. Supply one per form submission so a double-click or a retried request cannot double-credit.

## Response `200`

Successful Response

- object

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/kolens/apis/kolens-api.md) · [All operations](https://skmtc.dev/kolens/apis/kolens-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kolens/apis/kolens-api/revisions/5d6865ab0a24?raw)