Reference
Terminology & Endpoint Glossary
ATF uses different terms at different layers — spec, API, CLI, and UI. The differences are intentional: each surface optimizes for its audience. This page maps every public term to its canonical meaning.
See the specification: The normative receipt format is defined in atf-spec → spec/receipt.md. The normative verification procedure is in spec/verification.md.
Why ATF Uses Different Terms at Different Layers
ATF documentation spans four surfaces, each with its own audience:
- Specification (atf-spec) — normative, machine-precise, for implementors and auditors
- API / product docs (this site) — human-friendly, for developers integrating the API
- CLI — terse, for terminal output and scripting
- UI / dashboard — uppercase status labels, for at-a-glance readability
When you see "approved" in an API response and "allow" in the spec, they represent the same decision viewed through different lenses. Neither is wrong — they are different layers of the same system.
Decision Terminology
The most visible terminology difference is how a policy decision is expressed.
| Surface | Allow value | Deny value | Error value | Field / context |
|---|---|---|---|---|
| Spec (normative) | "allow" | "deny" | "error" | decision.status |
| API response | "approved" | "denied" | — | receipt.decision |
| API boolean | true | false | false | allow (top-level) |
| CLI exit code | 0 | 20 | 31 | process exit code |
| UI / dashboard | ALLOWED | DENIED | UNKNOWN | status badge |
| Product spec (v1) | "allowed" | "denied" | — | result.status |
Canonical source: spec/receipt.md defines decision.status as the normative enum: "allow" | "deny" | "error". All other surfaces are presentation-layer mappings of this value.
Hash Terminology
Two hash field names appear across ATF documentation. They describe the same cryptographic operation but appear at different layers.
| Term | Surface | Definition | Appears in |
|---|---|---|---|
content_hash | Spec & API | SHA-256 hex digest of the JCS-canonicalized receipt, excluding the hash field itself. 64 lowercase hex characters. | spec/receipt.md, API responses, verification procedure |
receipt_hash | Product docs & signing layer | Same SHA-256 computation. Used in the product-level receipt spec (v1), the signing endpoint, and execution receipts for on-chain anchoring. | receipt-specification-v1, anchoring-roadmap, signing API |
In practice, content_hash and receipt_hash refer to the same value — a deterministic SHA-256 over the canonical receipt data. The spec uses content_hash; the product layer uses receipt_hash when the hash is an input to signing or on-chain anchoring.
Concept Terminology
| Term pair | Distinction | When you will see each |
|---|---|---|
| receipt vs. proof | Receipt is the JSON artifact. Proof is the concept of evidence. | Spec and API always say “receipt.” Tutorials use “proof” when explaining why receipts matter. |
| verification vs. trust | Verification is the deterministic 5-step process for confirming receipt integrity. Trust is the design philosophy (zero-trust by default). | “Verification” in technical docs and CLI. “Trust” in architecture and threat-model discussions. |
| simulate vs. protect | Simulate evaluates policy without enforcement (advisory). Protect enforces the decision and stores a receipt (authoritative). | Quickstart uses simulate. Production flows use protect. See the endpoint table below. |
Endpoint Comparison
Two primary intent-evaluation endpoints appear in public tutorials. They serve different roles.
| Endpoint | Mode | Purpose | Audience | Where documented |
|---|---|---|---|---|
POST /v1/bot/protect | Authoritative | Enforces policy. Returns allow boolean + receipt with content_hash. The receipt is stored and verifiable. | Production bots | First Protected Trade |
POST /api/simulate | Advisory | Evaluates policy without enforcement. No receipt is stored. Rate limited (30 req/min public, 120 keyed). | Quickstart & sandbox | 5-Minute Quickstart |
POST /v1/receipts/verify | Verification | Verifies receipt integrity by recomputing and comparing content_hash. Returns valid: true/false. | Any verifier | Verification |
MCP equivalents: protect_transaction (authoritative), simulate_transaction (advisory), verify_receipt (verification). See MCP Integration for tool details.
Which Term Should I Use?
| If you are… | Use these terms |
|---|---|
| Writing a spec-compliant verifier | decision.status, content_hash, "allow" / "deny" / "error" |
| Integrating the REST API | allow (boolean), receipt.decision, receipt.content_hash |
| Scripting with the CLI | Exit code 0 (allow) or 20 (deny). Use atf bot protect --stdin |
| Building UI that displays decisions | ALLOWED / DENIED / UNKNOWN (uppercase badges) |
| Calling the signing or anchoring API | receipt_hash (same value as content_hash) |
Related Pages
- Receipts & Trust → What receipts prove and how to verify them
- Receipt Specification v1 → Product-level receipt format and fields
- Verification → content_hash in depth and --verify usage
- First Protected Trade → Golden path walkthrough using /v1/bot/protect
- MCP Integration → MCP tool names and advisory vs authoritative
- atf-spec → spec/receipt.md Normative receipt format (decision.status, content_hash)
- atf-spec → spec/verification.md Normative 5-step verification procedure