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.
VERDICT: PASS across commitment scheme, commitment reproduction, attestation, key binding and signature. Then run adversarial-test.py: 19 checks that try to make it lie, including that PASS, UNVERIFIED and FAIL stay distinct and that a registry misstating its own key_id is refused. Pair it with the replay kit — verification answers is this what you signed, replay answers was the decision reproducible, and neither substitutes for the other.Offline verification establishes that the receipt is exactly what this service signed. Hash-chain position is checked against the ledger and therefore requires the API — use POST /v1/verify for that. Verification does not re-execute the decision or re-evaluate the policy; it establishes that the recorded result is authentic and unaltered.
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 that value as before until it becomes null:
curl 'https://decrec.summitcognitive.ai/v1/ledger?limit=100'
# response: { "entries": [...], "next_before": 4531, ... }
curl 'https://decrec.summitcognitive.ai/v1/ledger?limit=100&before=4531'
offset is not supported. It 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 proves a receipt is authentic and unaltered. Replay proves the decision inside it was deterministic — 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>