Grant AI credits

POST

/entitlements/admin/orgs/{orgId}/credits

curl --request POST \
  --url https://api.sloose.com/entitlements/admin/orgs/org_9f3c/credits \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "pool": "included", "credits": 1, "ref": "example", "reason": "example", "expiresAt": "example" }'

• Production

Backoffice route: a staff session, or ADMIN_TOKEN; never a customer’s session. Idempotent on ref: granting twice with the same ref grants once. The same ref sent with another pool, credits or reason, or with an expiresAt other than the one it was granted with, is refused (409 REF_REUSED) rather than answered as the grant already made: a key names one grant, and a retry that changed what it asks for is not that grant. Written down as org.credits.

Authorizations

• sessionAuth
• adminToken

Parameters

Path Parameters

orgId

required

The organisation id.

string

Example

org_9f3c

The organisation id.

Request Body^required

Media typeapplication/json

object

pool

included credits reset each period; purchased ones carry over.

string | null

Allowed values: included purchased

credits

A positive number of credits to grant.

number | null

ref

Idempotency key. Generated if omitted.

string | null

reason

string | null

expiresAt

An ISO date (midnight UTC) or an ISO timestamp with Z or an offset, kept in UTC. Omitted or empty is the pool’s own: the period’s end for included, twelve months for purchased.

string | null

key

additional properties

Responses

201

Granted.

Media typeapplication/json

object

ref

required

string

balance

required

AI credits. Included credits reset each period; purchased ones do not.

object

included

required

number

purchased

required

number

reserved

required

number

available

required

Included + purchased − reserved

number

periodStart

required

string

periodEnd

required

string

Example^generated

{
  "ref": "example",
  "balance": {
    "included": 1,
    "purchased": 1,
    "reserved": 1,
    "available": 1,
    "periodStart": "example",
    "periodEnd": "example"
  }
}

400

pool is not one of the two pools, credits is not positive, or expiresAt is not an ISO date or timestamp.

Media typeapplication/json

object

error

required

string

key

additional properties

Example^generated

{
  "error": "example"
}

401

A bearer that is neither the token nor a live session (code: AUTH_REQUIRED).

Media typeapplication/json

The error envelope every non-2xx answer uses.

object

error

required

Human-readable explanation.

string

code

Machine-readable reason. Absent on a few legacy 400s.

string

key

additional properties

Example^generated

{
  "error": "example",
  "code": "example"
}

403

A customer’s session, an API token, or no bearer at all — not staff, and not the ADMIN_TOKEN (code: ADMIN_REQUIRED).

Media typeapplication/json

The error envelope every non-2xx answer uses.

object

error

required

Human-readable explanation.

string

code

Machine-readable reason. Absent on a few legacy 400s.

string

key

additional properties

Example^generated

{
  "error": "example",
  "code": "example"
}

409

ref was granted already, with another pool, number of credits or reason, or an expiry other than the one sent now. Nothing is granted, and nothing written down.

Media typeapplication/json

object

error

required

string

code

required

string

Allowed values: REF_REUSED

key

additional properties

Example

{
  "code": "REF_REUSED"
}

503

The restore switch is on (code: MAINTENANCE): every route but /health and /robots.txt is refused before anything is read, except the operator’s own POST /staff/people/{id}/delete with the ADMIN_TOKEN. Sloose is down for maintenance. Please try again in a few minutes.

Media typeapplication/json

object

error

required

string

code

required

string

Allowed value: MAINTENANCE

Example

{
  "code": "MAINTENANCE"
}

Headers

Retry-After

integer

Seconds until asking again is worth it (300 while the switch is on).