Deploy & Usage Guide
Get Decision Receipt running in your pipeline in under 10 minutes.
1. Get an API key
Sign up to receive an API key instantly. Include it as an X-API-Key header on all requests.
2. Issue your first receipt
404 from the public internet. POST /v1/evaluate and the other receipt-minting routes are contained at the edge, by design and regardless of credentials: an internet-reachable mint endpoint is a signing oracle. Production receipts are minted from signed webhook delivery. The request shape below is exact and is what you will send once your integration path is provisioned — ask your Summit contact. Verification needs no provisioning: POST /v1/verify is public and accepts any receipt.curl -X POST https://decrec.summitcognitive.ai/v1/evaluate \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{
"claim_id": "pr-42-merge",
"entity": "your-org/your-repo",
"claim": "AI agent requests merge for PR #42",
"sources": [
{"id": "ci", "type": "ci", "uri": "https://ci/run/1",
"confidence": 0.9, "content": "All tests pass"},
{"id": "review", "type": "code_review", "uri": "https://pr/42",
"confidence": 0.85, "content": "Approved"}
]
}'
3. Action-oriented flow
For agent integrations, use the three-step action flow:
# Step 1: Register the action
curl -X POST https://decrec.summitcognitive.ai/v1/actions \
-H "Content-Type: application/json" \
-d '{"action_id": "pr-42", "actor": {"name": "devin"},
"target": {"system": "github", "repository": "org/repo"}}'
# Step 2: Attach evidence
curl -X POST https://decrec.summitcognitive.ai/v1/actions/pr-42/evidence \
-H "Content-Type: application/json" \
-d '{"evidence": [{"type": "ci", "confidence": 0.9, "content": "pass"}]}'
# Step 3: Evaluate — receive Decision Receipt
curl -X POST https://decrec.summitcognitive.ai/v1/actions/pr-42/evaluate
4. GitHub Action
The hosted-issuance Action has no public cross-repository reference. Use the API in step 3 or the webhook in step 5 for an external integration. A provisioned customer Action must be reviewed and delivered through that customer's approved repository.
5. GitHub Webhook
Automatically evaluate every PR:
# Add webhook to your repo gh webhook create --repo your-org/your-repo \ --events pull_request \ --url https://decrec.summitcognitive.ai/v1/webhook/github
6. Verify a receipt
# Via API curl -X POST https://decrec.summitcognitive.ai/v1/verify \ -H "Content-Type: application/json" \ -d @receipt.json # Via CLI (offline). Supply the signing key, or the signature is NOT checked. curl https://decrec.summitcognitive.ai/v1/keys/server > server.pub.pem npx tsx apps/verify-cli/src/index.ts receipt.json --public-key server.pub.pem
The CLI reports three states, never a boolean: VERIFIED (exit 0) when the Ed25519 signature checks out, UNVERIFIED (exit 2) when it could not be checked — no key supplied, receipt unsigned, or signed by a key you did not supply — and INVALID (exit 1) when the receipt does not match its own signature. Without --public-key the signature is not verified and the result is UNVERIFIED, not VERIFIED.
d6763fdc…4c31, 21,275 bytes) and Action 0.2.3 (39b50ef6…2ed4, 28,388 bytes). They reject malformed Ed25519 trust keys, no longer report unsigned legacy cross-receipt linkage as PASS, and refuse repeated JSON object keys and integers outside the exactly-representable range at every JSON parse, including the pinned keyring. CLI source 0.1.5 is unreleased. CLI 0.1.2/0.1.3 and Action 0.2.1/0.2.2 are superseded but remain fetchable. Read the exact hashes and relying-party limitations.Legacy receipt signatures do not cover the separate chain coordinates. A structurally consistent link is not cryptographic proof of a recorded ledger position. Consult the ledger independently if chain placement matters. Verification does not establish key ownership, source truth, action execution, policy correctness, legal admissibility, or regulatory acceptance.
Inspect the public ledger
The ledger is paged backward with a cursor, not an offset. Start at the head, read next_before from the response, and pass it back verbatim as before until has_more is false and next_before is null. Following this loop to termination returns exactly total entries — that is the contract, and it is asserted by a test.
curl 'https://decrec.summitcognitive.ai/v1/ledger?limit=100'
# response: { "entries": [...], "total": 4647, "has_more": true,
# "next_before": "eyJ2IjoxLCJpIjo0NTQ3LCJyIjoicmNwdF8uLi4ifQ" }
curl 'https://decrec.summitcognitive.ai/v1/ledger?limit=100&before=eyJ2IjoxLCJpIjo0NTQ3LCJyIjoicmNwdF8uLi4ifQ'
next_before is an opaque string. Pass it back unchanged; do not parse it, order by it, or do arithmetic on it. It names a position in the ledger, and the page you receive is ordered by that same position — the cursor key and the ordering key are the same key, which is what makes the walk complete.
Do not page by chain_sequence. It is per-repository: several chains are interleaved in one ledger, so their sequence numbers restart and overlap. Until 2026-08-25 next_before published a bare chain_sequence integer, and a caller following the documented loop stopped after one page — 100 rows out of 4,647 — because a newer, shorter chain's sequence number 1 appeared in the first page and read as genesis. A bare integer before= is still accepted for those older callers and behaves exactly as it did, but it cannot enumerate the ledger; the response hands back an opaque cursor so a walk that starts that way corrects itself on the next request.
An unrecognised cursor returns 400 invalid_cursor rather than silently restarting at the head. offset is not supported and returns 400 unsupported_pagination_parameter rather than silently repeating the head page. For a single known receipt, skip pagination and use GET /v1/receipts/:receipt_id; that response includes both the receipt and its ledger entry.
7. Replay a decision
Verification checks the defined signed content under the selected key and detects modification within that signed scope; it does not authenticate unsigned fields or establish the key owner's identity. Replay checks whether the recorded decision is reproducible — that the same inputs, re-executed, produce the same result. These are different claims and we keep them separate.
curl -X POST https://decrec.summitcognitive.ai/v1/replay \
-H "Content-Type: application/json" \
-d '{"receipt": <receipt object>, "claim": <the original claim inputs>}'
A pass means: these exact inputs, re-executed now, reproduce the decision this receipt was issued for. You cannot substitute a different claim to manufacture a pass — the claim you supply is hashed and pinned against the receipt's committed evidence.inputs_hash before anything is re-executed, and a mismatch is refused with 409 inputs_do_not_match_receipt.
evidence.inputs_hash — a hash of the inputs, not the inputs. We cannot reconstruct them, and we do not publish them, because publishing customers' decision inputs would be a far larger disclosure than anything this service makes. So replay is available to whoever holds the inputs. It is deliberately not an anonymous public check. If you fetch a receipt from the public ledger and post it here without a claim, you will get 400 claim_required — that is the endpoint behaving correctly, not a fault.You do not have to take our word for the result either. The decision engine is deterministic given the claim alone — its clock is fixed precisely so a timestamp cannot vary between issue and replay — so you can run the same computation yourself against the shipped package and compare hashes without our cooperation. This endpoint is a convenience, not the root of trust:
hashCanonical(generateDecisionRecord(claim)) === receipt.replay.replay_hash
The response states its own scope: replay checks determinism only. It does not check signatures — use POST /v1/verify and the offline CLI for that.
./selftest.sh first: it drives all four outcomes and checks the exit codes, so you can confirm the tool is capable of failing before you believe it when it passes. Then alter one field of sample-claim.json yourself and watch it refuse. The bundle contains the actual production decision engine, not a reimplementation — a second implementation would only prove it agrees with itself. Verify the bytes with shasum -a 256 -c SHA256SUMS before running anything.8. Self-hosted deployment
docker compose up -d
The API starts on port 8787. Configure a reverse proxy (Caddy, nginx) for TLS.
The deployment source is a private repository. Pilot customers receive access as part of onboarding — ask your Summit Cognitive contact.
9. TypeScript SDK
Use the SDK for programmatic integration:
import { DecRec } from "@summit-dr/sdk";
const dr = new DecRec({ apiKey: "sk_decrec_..." });
// Quick PR evaluation
const result = await dr.evaluatePR({
repository: "your-org/your-repo",
pr: 42,
commit: "abc123",
branch: "feat/new-feature",
agent: "devin",
ciPassed: true,
reviewApproved: true,
});
console.info(result.receipt.admissibility.status);
// "ACCEPTED"
// Verify offline
const verified = await dr.verify(result.receipt);
console.info(verified.valid); // true
// Search receipts
const blocked = await dr.search({ verdict: "BLOCKED", limit: 10 });
// Repo analytics
const repos = await dr.repos();
10. Server public key
Download the server's Ed25519 public key, compare it with a key obtained through your chosen trust channel, and pin it for offline receipt verification:
curl https://decrec.summitcognitive.ai/v1/keys/server > server.pub.pem
11. Embed badges in your README
# Repo acceptance rate badge  # 14-day acceptance sparkline  # Embeddable dashboard widget <iframe src="https://decrec.summitcognitive.ai/embed/your-org/your-repo" width="400" height="300" frameborder="0"></iframe>