API REFERENCE

Credits and limits

What your account holds and what it may still convert today.

GET/v1/credits

Retrieve the credit balance

Derived from the ledger on every call: there is no balance column, since a cached total drifts under partial failure and the customer is the one who finds out. unlockCost is what unlocking one image costs, published so a client never hardcodes it; tier says which caps apply.

Errors

Every refusal carries its code and a requestId. Errors and retries.

curl
your key in VECSNAP_API_KEY
curl https://api.vecsnap.com/v1/credits \
  -H "Authorization: Bearer $VECSNAP_API_KEY"
200
example answers
{
  "balance": 184,
  "tier": "free",
  "unlockCost": 1
}

GET/v1/credits/history

List the credit history

Every entry that moved the caller's balance, newest first, a page at a time: what added credits (the sign-up grant, packs, a plan's months) and what spent them (unlocks, conversions paid in credits), each with what it meant. Pass a page's nextCursor back as cursor. Their sum is the balance (GET /credits).

Query

limitinteger, 1 to 100default 20
cursorstring
A page's nextCursor.

Errors

Every refusal carries its code and a requestId. Errors and retries.

curl
your key in VECSNAP_API_KEY
curl https://api.vecsnap.com/v1/credits/history \
  -H "Authorization: Bearer $VECSNAP_API_KEY"
200
example answers
{
  "object": "list",
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "at": "2026-10-24T12:00:00.000Z",
      "kind": "welcome",
      "amount": 0,
      "pocket": "plan",
      "subject": {
        "name": "Brand colors",
        "imageId": "00000000-0000-4000-8000-000000000000"
      }
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

GET/v1/limits

Retrieve today's limits

The caps that apply to the caller (a guest, a free account or a customer) and how much of today is used: the same count the create refuses by. usedToday counts free conversions (waiting ones included) and refunded holds; a stopped one never ran and is not counted.

Errors

Every refusal carries its code and a requestId. Errors and retries.

curl
your key in VECSNAP_API_KEY
curl https://api.vecsnap.com/v1/limits \
  -H "Authorization: Bearer $VECSNAP_API_KEY"
200
example answers
{
  "activeAtOnce": 1,
  "dailyFree": 0,
  "usedToday": 0,
  "resetsAt": "2026-10-24T12:00:00.000Z"
}