External credit API guide

1. Provision each UTC month

Set the entity allocation from your plan source of truth. New monthly windows start with zero consumption; they do not inherit last month's allocation. Use -1 for unlimited credits.

WINDOW_ID=$(date -u +%Y-%m)
curl -X PUT 'https://YOUR_BONGENTIC_HOST/api/v1/credits/allocation' \
  -H 'Content-Type: application/json' \
  -H "X-Token-Exchange-Secret: $API_SECRET" \
  --data-binary @- <<EOF
{"siteId":"example-site","entityId":"example-entity","allocation":100,"windowId":"$WINDOW_ID"}
EOF

A successful upsert returns HTTP 200 with an updated object.

2. Check before starting work

curl 'https://YOUR_BONGENTIC_HOST/api/v1/credits/balance?siteId=example-site&entityId=example-entity&userId=example-user' \
  -H "X-Token-Exchange-Secret: $API_SECRET"

Do not start work if exhausted is true or allocationLevel is global-default. The latter means no explicit allocation was provisioned. Validate that the user belongs to the entity in your own system; this API does not check membership.

3. Charge completed work

After work succeeds, calculate its credit cost and send one deduction. Use the real completion time and a stable, unique eventIdfor that work item. A scheduled job must charge the user who owns or started it, not a participant ID.

COMPLETED_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)
curl -X POST 'https://YOUR_BONGENTIC_HOST/api/v1/credits/deductions' \
  -H 'Content-Type: application/json' \
  -H "X-Token-Exchange-Secret: $API_SECRET" \
  --data-binary @- <<EOF
{"eventId":"job-123","caller":"apricot","siteId":"example-site","entityId":"example-entity","userId":"example-user","credits":10,"actionType":"report","pricingVersion":"v1","occurredAt":"$COMPLETED_AT"}
EOF

Capture COMPLETED_AT when the work actually finishes; reuse that value if the request needs a retry. For a new deduction, the API accepts times no more than five minutes in the future and no earlier than the start of the previous UTC month. An identical replay remains valid later. Once work succeeds, send the deduction even if the wallet has since emptied. HTTP 201 means it was recorded; exhausted: true and a negative remaining are possible.

4. Handle retries and errors

HTTP 200 means the identical deduction was already recorded. Treat both 200 and 201 as success. On a timeout or HTTP 500, 502, 503, or 504, retry with the same caller, eventId, and unchanged request body. Do not create a new event ID for a retry.

HTTP 400 means fix the request; 403 means fix authentication; 404 means provision an explicit allocation; 409 means that caller and event ID were already used for different data. None is a reason to retry the same bad request indefinitely.

5. Read entity usage

curl "https://YOUR_BONGENTIC_HOST/api/v1/credits/consumption/entity?siteId=example-site&entityId=example-entity&windowId=$WINDOW_ID&limit=100" \
  -H "X-Token-Exchange-Secret: $API_SECRET"

The response lists users with non-zero consumption. If it contains nextCursor, repeat the request with that value as the cursor query parameter until it is absent. Entity reports are complete only from the first full UTC month after the usage index rollout; older months can omit users. Individual balance reads remain accurate.