GET /credits

The GET /credits endpoint lets you inspect the remaining credit balance tied to your API key. It never deducts credits and is safe to call whenever you need to enforce spending limits or display usage totals in your application.

Request

• Method: GET
• Path: /credits
• Authentication: Required (x-api-key)
• Headers:
  • x-api-key: Your 64-character hexadecimal access token.
  • Optional accept: application/json

GET https://api.brookmimir.com/credits
x-api-key: YOUR_API_KEY
accept: application/json

Successful response

• HTTP status: 200 OK
• Body schema: CreditResponse
  • status (integer or null): Numeric result indicator.
  • message (string or null): Human-readable summary.
  • current_balance (integer or null): Remaining credits tied to the token.

{
  "status": 200,
  "message": "Credits retrieved",
  "current_balance": 4287
}

Field reference

Field	Type	Description
status	integer or null	Mirrors the HTTP outcome (200 on success).
message	string or null	Supplemental details about the lookup.
current_balance	integer or null	Credits remaining; null indicates the token was invalid.

Error handling

HTTP status	Scenario	Notes
400	Missing or malformed headers	Confirm the x-api-key header is present and 64 hex characters.
401 / 403	Authentication failure	The key is unknown, inactive, or revoked.
402	Balance depleted	Returned when credits have reached zero.
404	Token not recognized	Verify the key and regenerate if necessary.
5xx	Temporary service issue	Retry with exponential backoff.

Recommended usage

1. Budget enforcement: Call /credits before invoking billable endpoints such as /document, /query, or /face/search.
2. Usage dashboards: Display the returned current_balance to give operators real-time visibility into consumption.
3. Alerting: Trigger notifications when the balance falls below internal thresholds so teams can replenish credits.
4. Audit trails: Log every response alongside the calling service or user to simplify support investigations.

Pair /credits with /profile when you need a full snapshot of account context prior to running high-cost workloads.