TUTORIAL

Triage the ledger

Something looks off with one of your agents. A teammate flags that merges that used to sail through are suddenly getting stopped, or you see an escalation land in a channel and want to know whether it is a one-off or a pattern. This tutorial walks you through a real investigation using the read-only ledger endpoints — most of which need no authentication — narrowing from the whole system down to a single suspect receipt, then confirming that what you found is genuine.

Every request below targets the live API at https://decrec.summitcognitive.ai and pipes through jq so you can see the shape of each response. Read endpoints require no API key, so you can run them right now.

1. Get the lay of the land

Start wide. Before you accuse any single agent, you want the totals: how many receipts exist, how many were accepted, and which agents and repositories are even in play. Two endpoints give you that.

REQUEST

curl -s https://decrec.summitcognitive.ai/v1/overview | jq .

The overview returns the system-wide picture — receipt counts, the set of agents, the set of repositories, and the overall acceptance rate. If acceptance has dropped below where you expect it to sit, that confirms the smell is real and not just one noisy notification. Now pull the raw tallies:

REQUEST

curl -s https://decrec.summitcognitive.ai/v1/ledger/stats | jq .

RESPONSE

{
  "total": 2183,
  "accepted": 2134,
  "blocked": 31,
  "escalated": 18,
  "non_deterministic": 12,
  "agents": ["claude-code", "dependabot", "renovate"],
  "repositories": ["acme-corp/widget-api", "acme-corp/infra"]
}

Read this as a baseline. The blocked and escalated counts tell you how much friction exists across everything; the agents and repositories arrays tell you where to look next. Note the names — you will filter on them in the following steps.

2. Zoom into one agent

You notice the totals are fine in aggregate but you still suspect one actor. Get the per-agent breakdown so you can see which agent is contributing the blocks:

REQUEST

curl -s https://decrec.summitcognitive.ai/v1/agents | jq .

This returns one summary per agent. If claude-code shows a cluster of blocked decisions out of proportion to its volume, that is your lead. Pull exactly those decisions with a filtered search — combine the agent filter with a verdict filter to list only its blocked receipts:

REQUEST

curl -s "https://decrec.summitcognitive.ai/v1/receipts/search?agent=claude-code&verdict=BLOCKED" | jq .

Now you have the specific receipts where a BLOCKED verdict was issued for that agent. Scan their reason fields and the repositories they touch. A run of blocks all citing the same failed policy rule — say, too few evidence sources — points you at what changed, not just that something did.

3. Look at a repo over time

The blocked receipts cluster around one repository. The next question is when the trouble started. A spike on a particular day usually lines up with a change you can name — a policy edit, a CI regression, a dependency bump. Ask for the daily timeline scoped to that repo:

REQUEST

curl -s "https://decrec.summitcognitive.ai/v1/receipts/timeline?repository=acme-corp/widget-api" | jq .

The timeline returns daily receipt counts for the repository. Look for the inflection point — the day blocks or escalations jump from background noise to a visible spike. That date is your anchor. Whatever you changed around then is the most likely cause, and the PRs from that window are the ones worth opening up next.

4. Investigate a specific PR

You pick a PR from the spike window. The interesting case is a PR that was pushed to more than once: an early push that passed, a later push that got blocked. The diff endpoint lines up every receipt for the same PR across its pushes so you can see what moved:

REQUEST

curl -s "https://decrec.summitcognitive.ai/v1/receipts/diff?repository=acme-corp/widget-api&pr=42" | jq .

Read it as a story across pushes. Did the verdict flip from ALLOWED to BLOCKED? Did the evidence degrade — fewer sources, a lower average confidence, a missing review — between one push and the next? Often the answer is mundane and useful: a later push dropped the passing test run, so the evidence no longer cleared the policy. The diff turns a vague "the agent is misbehaving" into a precise "this push lost its CI evidence."

5. Compare two suspect receipts

To confirm the difference, put the two receipts side by side. Take the receipt IDs from the diff — the one that passed and the one that did not — and compare them directly:

REQUEST

curl -s "https://decrec.summitcognitive.ai/v1/receipts/compare?ids=dr-aaa111,dr-bbb222" | jq .

The comparison aligns the two receipts field by field — their verdicts, their evidence summaries, their policy results. This is where the root cause becomes unambiguous: you can see the exact source that was present in one receipt and absent in the other, or the policy check that passed before and failed after. You now have a concrete, defensible account of what happened.

6. Confirm integrity of what you found

Before you act on a finding — or escalate it — confirm the receipt you are reasoning about is genuine and unaltered. A receipt is only evidence if it survives a skeptical check. Post the receipt of interest to /v1/verify, which needs no authentication:

REQUEST

curl -s https://decrec.summitcognitive.ai/v1/verify \
  -H "Content-Type: application/json" \
  -d @receipt.json | jq .

A valid: true response means the receipt's hash still matches the ledger and its Ed25519 signature checks out — the record you are looking at is the record that was issued. For the full mechanics, including offline verification against the published public key, see Verifying receipts.

Finally, widen back out one notch and check whether the repository you investigated is an outlier against its peers. The per-repository summary reports acceptance rates:

REQUEST

curl -s https://decrec.summitcognitive.ai/v1/repos | jq .

If one repository's acceptance rate sits well below the others, that is a signal worth a standing eye — not necessarily a bug, but a repo whose evidence or policy posture differs from the rest of your fleet. Triage is rarely a single answer; it is knowing which repo, which agent, and which push to watch next.

For the complete map of every endpoint used here and the rest of the platform, see Platform surfaces. For the conceptual grounding on why these records chain together into a tamper-evident audit trail, see The ledger and audit chain.