API Reference

Complete reference for all Credits REST API endpoints. Each endpoint includes code examples in curl, Node.js, and Python. For TypeScript/JavaScript, use the official @credits-dev/sdk for type-safe access—it mirrors these endpoints and supports both accountId and externalId.

Authenticate with API key

Each request must include your Credits API key in the X-API-Key header.

curl -X GET "https://api.credits.dev/v1/accounts/balance?accountId=acc_123" \
  -H "X-API-Key: {YOUR_API_KEY}"

Accounts

Create and manage customer accounts with dual ID support (internal + external IDs).

createlistgetbalanceplans

Plans

Create and manage credit plans, assign them to accounts.

listcreatearchiveassign

Transactions

View transaction history per account and create manual transactions.

listcreate

Usage Tracking

Track LLM usage per account or system-wide with automatic cost calculation.

recordlistsummary

Balance

Get account balances and perform simple balance adjustments (add / deduct).

balanceadddeduct

Reservations

List and manage reservations per account to prevent leaks during concurrent operations.

createlistconfirmcancel

Models

Get available models and calculate usage costs.

listgetcalculate

End-to-end flow

Example showing a typical sequence: reserve credits → perform operation → confirm reservation.

Reserve, use, and confirm credits

# 1. Reserve credits for an account
curl -X POST "https://api.credits.dev/v1/reservations/create" \
  -H "X-API-Key: {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_abc123",
    "amount": 100,
    "operation": "chat-completion",
    "model": "gpt-4o"
  }'

# 2. Perform your LLM operation here...

# 3. Confirm reservation with actual usage
curl -X POST "https://api.credits.dev/v1/reservations/confirm" \
  -H "X-API-Key: {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "reservationId": "res_abc123",
    "actualAmount": 85
  }'