Credit API

How external services reserve and settle credits — lock before acting, settle after the outcome.

Every billable action on the platform costs credits, tracked per Business Unit. Internally, the credit pipeline is driven by EventBridge events through FIFO queues — but external Talentino services (the first consumer is the Request Info service) need a synchronous yes/no on credit availability before they act. The Credit API is that contract: two bearer-authenticated endpoints on the talentino-sst backend.

These endpoints are for Talentino services, not partners. They are secured with a static bearer key shared per-service (the CREDITS_API_KEY SST secret), not the tlt_ partner key.

Lock before act, settle after the outcome

The flow has exactly two steps around your action:

POST /credits/lock — before performing the action. Synchronously checks sufficiency — (subscription + on-demand credits remaining − already-locked reservations) ≥ action cost — and reserves the cost. 200 means go ahead; 402 means the Business Unit can't afford it, so don't act.
POST /credits/settle — after the action completes, reporting the outcome. success: true consumes the reserved credits (balance debit + lock drawdown); success: false releases the reservation without any debit. Settlement returns 202 and completes asynchronously through the internal FIFO credit pipeline (per-Business-Unit ordering, dedup, DLQ).

lock (200) ──> perform the action ──> settle { success: true }   → credits consumed
                        └─ it failed ─> settle { success: false } → lock released, no debit
lock (402) ──> don't act — insufficient credits

Idempotency via your `operation_id`

Both calls carry a caller-supplied operation_id — your stable record id for the operation. It does double duty:

Retry safety: locking is idempotent on operation_id. Retrying a lock (e.g. after a timeout) never reserves twice and returns the same 200. Retrying a settle republishes the internal event, which the pipeline's dedup keys turn into a no-op.
Correlation: the settle call targets the lock created with the same operation_id. A settle for an unknown operation_id — or one whose lock belongs to a different Business Unit — returns 404 lock_not_found (the two cases are deliberately indistinguishable).

Locks don't expire

A reservation stays held until it is settled. There is no auto-expiry yet: if your service locks credits and never calls settle, those credits remain reserved and reduce the Business Unit's spendable balance. Always settle — including on failure paths — even if the action itself failed.

Billable Action Types

The API accepts any billable Action Type; costs live in the action_types table (so pricing changes require no API change):

Action Type	What it bills
`process_resume`	Ingesting and extracting a Resume document
`process_job_requirements`	Extracting requirements from a job document
`score_resume`	Scoring one Resume against a Job Match
`request_info`	The billable act of requesting additional information from a candidate by email (1 credit)

Other responses to handle

401 — missing or wrong bearer key.
409 (lock only) — credits_allocation_in_progress: a credit (re)allocation for the Business Unit is running; retry after a short delay.
400 — validation error; the body lists the offending fields.

See the reference pages for the exact request/response shapes: POST /credits/lock and POST /credits/settle.