Reservations API

Manage credit reservations to prevent leaks during concurrent operations.

About Reservations

Reservations prevent credit leaks by locking credits before expensive operations (like LLM calls). This ensures credits are available when the operation completes, even if multiple operations run concurrently.

POST/v1/reservations/create

Create a new reservation to lock credits before an expensive operation.

Create reservation

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_123",
    "amount": 100,
    "operation": "chat-completion",
    "model": "gpt-4o"
  }'

Request Body

{
  "accountId": "acc_123",
  "amount": 100,
  "operation": "chat-completion",
  "model": "gpt-4o"
}

Response

{
  "success": true,
  "reservation": {
    "id": "res_abc123",
    "accountId": "acc_123",
    "amount": 100,
    "status": "pending",
    "expiresAt": "2024-01-15T10:05:00Z",
    "metadata": {
      "operation": "chat-completion",
      "model": "gpt-4o"
    }
  }
}

GET/v1/reservations?accountId=...

List reservations for a single account. Filter by activeOnly.

List reservations for an account

curl -X GET "https://api.credits.dev/v1/reservations?accountId=acc_123&activeOnly=true" \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "success": true,
  "reservations": [
    {
      "id": "res_abc123",
      "accountId": "acc_123",
      "amount": 100,
      "status": "pending",
      "createdAt": "2024-01-15T10:00:00Z",
      "expiresAt": "2024-01-15T10:05:00Z",
      "metadata": { "operation": "chat-completion" }
    }
  ]
}

POST/v1/reservations/confirm

Confirm a reservation with the actual amount used. Creates a transaction and releases unused credits.

Confirm reservation

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
  }'

Request Body

{
  "reservationId": "res_abc123",
  "actualAmount": 85
}

Response

{
  "success": true,
  "reservationId": "res_abc123",
  "transactionId": "txn_xyz789",
  "reservedAmount": 100,
  "actualAmount": 85,
  "balance": 915
}

POST/v1/reservations/cancel

Cancel a reservation and release all reserved credits back to available balance.

Cancel reservation

curl -X POST "https://api.credits.dev/v1/reservations/cancel" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reservationId": "res_abc123"
  }'

Request Body

{
  "reservationId": "res_abc123"
}

Response

{
  "success": true,
  "reservationId": "res_abc123",
  "amountReleased": 100,
  "accountId": "acc_123"
}