Skip to main content

​
Base URL

  • Production: https://api.example.com
  • Staging: https://staging-api.example.com
  • Local: http://localhost:8080

​
Conventions

  • Content-Type: application/json
  • Date/Time: ISO 8601 (UTC)
  • Pagination: limit, offset
  • Error format: See “Error Responses (Global)” in docs/api/endpoint-template.md

​
Endpoints

​
GET /api/v1/credits/transactions

Summary: List credit transactions for the authenticated user. Idempotent: Yes Tags: credits

​
Request

Headers
  • Content-Type: application/json
Query Params
NameTypeRequiredDefaultDescriptionExample
user_idstring (uuid)No-Target user ID (admins only)550e8400-e29b-41d4-a716-446655440000
limitintegerNo50Number of transactions to return (1-100)50
offsetintegerNo0Number of transactions to skip0

​
Responses

200 OK - List of credit transactions 
{
  "transactions": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "user_id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "grant",
      "amount": 100,
      "balance_after": 500,
      "reason": "Manual adjustment",
      "metadata": { "source": "admin" },
      "created_at": "2023-01-01T12:00:00Z"
    }
  ],
  "total": 120,
  "limit": 50,
  "offset": 0
}
Response Fields
FieldTypeDescription
transactionsarrayCredit transactions
transactions[].idstringTransaction UUID
transactions[].user_idstringUser UUID
transactions[].typestringgrant or deduction
transactions[].amountintegerCredit delta
transactions[].balance_afterintegerBalance after the transaction
transactions[].reasonstringOptional reason
transactions[].metadataobjectOptional metadata
transactions[].created_atstringISO 8601 timestamp
totalintegerTotal number of transactions
limitintegerPage size
offsetintegerOffset into the result set
400 Bad Request - Invalid query parameters 
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "limit must be less than or equal to 100"
  }
}
401 Unauthorized 
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid token"
  }
}
404 Not Found 
{
  "error": {
    "code": "NOT_FOUND",
    "message": "User not found"
  }
}
500 Internal Server Error 
{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Unexpected server error"
  }
}

​
Notes

  • Admin tokens that do not map to a user UUID must supply user_id.

​
Examples

cURL 
curl -X GET \
  'https://api.example.com/api/v1/credits/transactions?limit=50&offset=0'