Decision states and request flow

The most important thing to understand about Ledgix is not the internal implementation. It is the set of statuses your application and team must handle correctly.

The four statuses

What happens in practice

1. 01

   Your application sends the request

   The request includes the exact tool name and tool arguments you plan to execute. This is the part your code controls directly.
2. 02

   Ledgix evaluates the request

   Ledgix checks the request against your uploaded policy content and the current review settings for your tenant.
3. 03

   You handle the status

   Approved and denied are final. Pending review means a human must decide later. Processing means the request is still resolving.
4. 04

   Your team follows up if needed

   Reviewers work from the dashboard or review API. Audit-focused teams can later use ledger and proof endpoints to verify what happened.

When to poll

Poll GET /clearance-status/{request_id} only when the request is still processing or pending_review.

• The SDKs already do this for you by default.
• Use manual polling only when you need custom timeout or user-experience behavior.
• Keep the request_id so your application and the dashboard can refer to the same request later.

How to think about pending_review

pending_review is not a partial failure. It means Ledgix is deliberately pausing an action because your tenant settings require a human decision before the action can continue.

Common reasons:

• the confidence score is below your threshold
• your team intentionally runs with a stricter threshold during rollout
• a borderline request needs policy context that a reviewer can validate faster than the model

What your application should do

• On approved: execute the action and keep the request_id.
• On denied: stop the action and surface the reason clearly.
• On pending_review: show a waiting state or enqueue follow-up work instead of retrying immediately.
• On processing: wait and poll again, or let the SDK do it.

When audit data becomes useful

Terminal decisions show up in the customer ledger and later in checkpoint and proof endpoints. Most teams do not need those APIs for day-one integration, but they become useful when:

• you need to verify a specific request after the fact
• an auditor asks for tamper-evident evidence
• you want a second verification step outside your app runtime

Practical integration rules

• Do not collapse pending_review into denied. They are different customer workflows.
• Do not run the tool before Ledgix returns approved.
• Do not reuse a token across different payloads or different actions.
• Do not throw away request_id; it is the easiest way to reconcile application logs with the dashboard.