Skip to content

Rebuild public API reference into full infrastructure docs page #248

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
GsCommand merged 1 commit into from
May 21, 2026
+227 −5
Merged

Rebuild public API reference into full infrastructure docs page #248

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
232 changes: 227 additions & 5 deletions public/api.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,227 @@
<!doctype html><html lang="en"><head><meta charset="utf-8" /><meta name="viewport" content="width=device-width,initial-scale=1" /><title>CommandLayer API Index</title><link rel="icon" href="/icon2.png" /><link rel="stylesheet" href="/css/site.css" /></head><body><main class="container" style="padding:48px 0"><h1>API Index</h1><ul><li>Runtime API -> <a href="/runtime.html">/runtime.html</a></li><li>MCP Transport -> <a href="/mcp.html">/mcp.html</a></li><li>Trust Verification endpoints -> <a href="/trust-verification.html">/trust-verification.html</a></li><li>Website verifier surfaces -> <a href="/verify.html">/verify.html</a></li></ul><h2>Response states</h2><ul><li>VALID / VERIFIED</li><li>INVALID</li><li>TRANSPORT_ERROR</li></ul><h2>Example runtime sign</h2><pre>curl -X POST https://runtime.commandlayer.org/trust-verification/sign/v1.0.0 \
-H "Content-Type: application/json" \
-d '{"payload":{"subject":"demo"}}'</pre><h2>Example runtime verify</h2><pre>curl -X POST https://runtime.commandlayer.org/verify \
-H "Content-Type: application/json" \
-d '{"receipt":{}}'</pre><p>Note: website <code>/api/verify</code> route behavior should be treated cautiously unless separately validated for canonical production semantics.</p></main></body></html>
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width,initial-scale=1" />
<title>CommandLayer API Reference | Infrastructure Surface Map</title>
<meta name="description" content="API surfaces for verifiable agent actions across runtime signing, receipt verification, MCP transport, and website verifier endpoints." />
<link rel="icon" href="/icon2.png" />
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&display=swap" rel="stylesheet" />
<link rel="stylesheet" href="/css/site.css" />
<style>
.brand{gap:0}.brand img{height:68px;width:auto;object-fit:contain}.brand span{display:none}.nav-links{display:flex;align-items:center;gap:2px;list-style:none;flex-wrap:wrap;margin:0;padding:0}.nav-links a{color:var(--muted);text-decoration:none;font-size:14px;font-weight:500;padding:7px 12px;border-radius:8px;background:none;border:none;font-family:inherit}.nav-links a:hover,.nav-drop:hover>a,.nav-drop:focus-within>a,.nav-drop>a.active{color:var(--text);background:var(--surface)}.nav-drop{position:relative}.nav-drop>a{display:inline-flex;align-items:center;gap:4px}.nav-drop-menu{position:absolute;top:calc(100% - 1px);left:0;background:#fff;border:1px solid var(--border);border-radius:12px;box-shadow:0 10px 34px rgba(15,23,42,.12);padding:8px;display:none;min-width:260px;z-index:200}.nav-drop-menu::before{content:"";position:absolute;left:0;right:0;top:-8px;height:8px}.nav-drop-menu a{display:block;white-space:nowrap}.nav-drop:hover .nav-drop-menu,.nav-drop:focus-within .nav-drop-menu{display:grid}
.api-shell{padding:64px 0 88px}.section{margin-top:26px}.api-card{background:#fff;border:1px solid var(--border);border-radius:18px;padding:24px;box-shadow:0 1px 2px rgba(15,23,42,.04),0 6px 20px rgba(99,91,255,.04)}
.grid-3{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:14px}.grid-2{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:14px}.surface-card,.status-card,.path-card{border:1px solid var(--border);border-radius:14px;padding:16px;background:#fff}.surface-card p,.status-card p,.path-card p,.api-card p,.api-card li{color:var(--text-2);line-height:1.65}
.surface-card h3,.status-card h3,.path-card h3{font-size:1.03rem;margin-bottom:6px}.endpoint-list{display:grid;gap:10px}.endpoint{border:1px solid var(--border);border-radius:14px;padding:14px;background:var(--surface)}.endpoint code{font-size:13px}
.inline-note{border-left:4px solid var(--purple);background:linear-gradient(180deg,#F9FAFF 0%,#F3F6FF 100%);padding:14px;border-radius:0 12px 12px 0;margin:12px 0}
.code-panel{background:#0E1322;color:#E2E8F0;border-radius:14px;border:1px solid rgba(30,41,59,.3);padding:16px;overflow:auto;font:13px/1.7 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace}
.code-panel code{color:inherit}.proof-status{margin-top:16px;background:#f8fbff;border:1px solid #d8e5ff;border-radius:14px;padding:14px 16px;color:var(--text-2);font-size:14px;line-height:1.6}
.cta-grid{display:grid;grid-template-columns:repeat(4,minmax(0,1fr));gap:10px}.cta-grid a{text-decoration:none;text-align:center;padding:11px 12px;border-radius:12px;border:1px solid var(--border);font-weight:700;color:var(--text-2);background:#fff}.cta-grid a.primary{background:var(--gradient);color:#fff;border-color:rgba(99,91,255,.5)}
footer{border-top:1px solid var(--border);background:#fff}.footer-grid{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:24px;padding:36px 0}.footer-grid h4{font-size:14px;margin-bottom:10px}.footer-grid a{display:block;color:var(--text-2);margin:8px 0;font-size:14px}
@media(max-width:960px){.grid-3,.grid-2,.cta-grid,.footer-grid{grid-template-columns:1fr}.api-shell{padding:42px 0 64px}.nav-drop{width:100%}.nav-drop-menu{position:static;display:grid;margin-top:2px;min-width:0;box-shadow:none}}
</style>
</head>
<body>
<nav>
<div class="container nav-inner">
<a href="/" class="brand"><img src="/commandlayer-logo.png" alt="CommandLayer" /><span>CommandLayer</span></a>
<ul class="nav-links">
<li><a href="/">Home</a></li>
<li><a href="/protocol.html">Protocol</a></li>
<li><a href="/capabilities.html">Capabilities</a></li>
<li><a href="/verify.html">Verifier</a></li>
<li><a href="/sdk-records.html">SDK</a></li>
<li class="nav-drop">
<a href="/docs.html" class="active" aria-haspopup="true">Docs ▾</a>
<div class="nav-drop-menu">
<a href="/docs.html">Docs Home</a><a href="/docs/wrap-your-agent.html">Wrap Your Agent</a><a href="/stack-proof-demo.html">Production Proof</a><a href="/runtime.html">Runtime</a><a href="/mcp.html">MCP Bridge</a><a href="/schemas.html">Schemas</a><a href="/api.html">API Reference</a><a href="/trust-verification.html">Trust Verification</a><a href="/claim.html">Claim / Namespace Activation</a>
</div>
</li>
<li><a href="/claim.html">Claim</a></li>
<li><a href="https://github.com/commandlayer" target="_blank" rel="noopener">GitHub</a></li>
</ul>
</div>
</nav>

<section class="hero">
<div class="container">
<div class="hero-badge"><span class="badge-dot"></span>API Reference</div>
<h1 class="hero-h1">API surfaces for verifiable agent actions.</h1>
<p class="hero-sub">Use CommandLayer runtime, verifier, MCP, and website verifier surfaces to issue signed receipts, verify proof, and integrate verifiable agent workflows.</p>
<div class="hero-actions">
<a class="btn btn-primary btn-lg" href="/verify.html">Try Verifier</a>
<a class="btn btn-secondary btn-lg" href="/stack-proof-demo.html">View Production Proof</a>
</div>
<div class="proof-status"><strong>Production proof status:</strong> Runtime production is live and signs canonical Trust Verification receipts. MCP E2E against production runtime passes: STEP 1 SIGNED, STEP 2 VERIFIED, STEP 3 TAMPERED INVALID. Runtime signer is <code>runtime.commandlayer.eth</code> with <code>kid=vC4WbcNoq2znSCiQ</code>. Canonical proof is <code>metadata.proof.canonicalization=json.sorted_keys.v1</code>, <code>metadata.proof.hash.alg=SHA-256</code>, <code>metadata.proof.signature.alg=Ed25519</code>.</div>
</div>
</section>

<main class="container api-shell">
<section class="api-card section">
<h2>API surface overview</h2>
<p>CommandLayer APIs expose runtime signing, receipt verification, MCP transport, and website verifier surfaces for verifiable agent actions.</p>
<div class="grid-3" style="margin-top:14px">
<a class="surface-card" href="/runtime.html"><h3>Runtime API</h3><p>Production execution/signing and verification surface.</p></a>
<a class="surface-card" href="/mcp.html"><h3>MCP Transport</h3><p>Bridge for MCP clients. Transport changes; proof model does not.</p></a>
<a class="surface-card" href="/trust-verification.html"><h3>Trust Verification</h3><p>Canonical Trust Verification v1 endpoints and verbs.</p></a>
<a class="surface-card" href="/verify.html"><h3>Website Verifier</h3><p>Human-facing verification UI and public verifier surfaces.</p></a>
<a class="surface-card" href="/sdk-records.html"><h3>SDK</h3><p>Developer wrapper for receipts and verifier calls.</p></a>
<a class="surface-card" href="/schemas.html"><h3>Schemas</h3><p>Request/receipt/proof structure.</p></a>
</div>
</section>

<section class="api-card section">
<h2>Runtime endpoints</h2>
<div class="endpoint-list">
<div class="endpoint"><strong>GET</strong> <code>https://runtime.commandlayer.org/health</code></div>
<div class="endpoint"><strong>POST</strong> <code>https://runtime.commandlayer.org/verify</code></div>
<div class="endpoint"><strong>POST</strong> <code>https://runtime.commandlayer.org/trust-verification/{verb}/v1.0.0</code></div>
</div>
<h3 style="margin-top:14px">Supported Trust Verification verbs</h3>
<p><code>sign</code>, <code>attest</code>, <code>authorize</code>, <code>approve</code>, <code>reject</code>, <code>permit</code>, <code>grant</code>, <code>authenticate</code>, <code>endorse</code></p>
<div class="inline-note"><strong>Important:</strong> <code>verify</code> is the verifier action/surface, not a signer endpoint.</div>
</section>

<section class="api-card section">
<h2>Runtime sign example</h2>
<pre class="code-panel"><code>curl -X POST https://runtime.commandlayer.org/trust-verification/sign/v1.0.0 \
-H "content-type: application/json" \
-d '{"payload":{"message":"hello from CommandLayer"}}'</code></pre>
<h3 style="margin-top:14px">Expected response shape</h3>
<pre class="code-panel"><code>{
"receipt": {
"verb": "sign",
"class": "trust-verification",
"result": {
"payload": {
"message": "hello from CommandLayer"
}
},
"metadata": {
"proof": {
"canonicalization": "json.sorted_keys.v1",
"hash": {
"alg": "SHA-256",
"value": "..."
},
"signature": {
"alg": "Ed25519",
"kid": "vC4WbcNoq2znSCiQ",
"value": "..."
},
"signer_id": "runtime.commandlayer.eth"
}
}
}
}</code></pre>
</section>

<section class="api-card section">
<h2>Runtime verify example</h2>
<pre class="code-panel"><code>curl -X POST https://runtime.commandlayer.org/verify \
-H "content-type: application/json" \
-d '{"receipt":{...}}'</code></pre>
<div class="grid-3" style="margin-top:14px">
<div class="status-card"><h3>VALID / VERIFIED</h3><p>Hash and signature checks passed.</p></div>
<div class="status-card"><h3>INVALID</h3><p>Proof failed, payload changed, unsupported proof, wrong signer/key, or missing proof.</p></div>
<div class="status-card"><h3>TRANSPORT_ERROR</h3><p>Verifier/runtime unavailable or request failed.</p></div>
</div>
</section>

<section class="api-card section">
<h2>MCP endpoint section</h2>
<div class="endpoint-list">
<div class="endpoint"><strong>GET</strong> <code>https://mcp.commandlayer.org/health</code></div>
<div class="endpoint"><strong>POST</strong> <code>https://mcp.commandlayer.org/mcp</code></div>
</div>
<div class="inline-note"><strong>Important:</strong> <code>GET /mcp</code> is not expected to work. <code>/mcp</code> is POST-only MCP transport.</div>
<h3>MCP tools</h3>
<p><code>clas.trust-verification.verify</code>, <code>clas.trust-verification.sign</code>, <code>clas.trust-verification.attest</code>, <code>clas.trust-verification.authorize</code>, <code>clas.trust-verification.approve</code>, <code>clas.trust-verification.reject</code>, <code>clas.trust-verification.permit</code>, <code>clas.trust-verification.grant</code>, <code>clas.trust-verification.authenticate</code>, <code>clas.trust-verification.endorse</code></p>
<div class="inline-note"><strong>Trust boundary:</strong> The proof model is identical whether an action is called through MCP or direct HTTP. MCP changes transport, not trust. Runtime still signs. Verifier still validates. MCP does not hold keys.</div>
</section>

<section class="api-card section">
<h2>Website verifier surfaces</h2>
<ul>
<li><code>/verify.html</code> — Interactive manual verifier.</li>
<li><code>/api/verify</code> — Website verifier API surface; treat as a website-facing verifier surface unless separately validated for parity with runtime <code>/verify</code>.</li>
<li><code>/api/agents/verifyagent</code> — VerifyAgent metadata/API alias surface if present.</li>
</ul>
<div class="inline-note"><strong>Warning:</strong> Do not treat <code>/api/verify</code> as the canonical production verifier unless tests prove parity with runtime <code>/verify</code>.</div>
</section>

<section class="api-card section">
<h2>Request/response conventions</h2>
<p><strong>Content-Type:</strong> <code>application/json</code></p>
<div class="grid-2">
<div>
<h3>Input for signer endpoints</h3>
<pre class="code-panel"><code>{
"payload": {}
}</code></pre>
</div>
<div>
<h3>Input for verifier endpoints</h3>
<pre class="code-panel"><code>{
"receipt": {}
}</code></pre>
</div>
</div>
<h3 style="margin-top:14px">Canonical proof fields</h3>
<p><code>metadata.proof.canonicalization</code><br/><code>metadata.proof.hash.alg</code><br/><code>metadata.proof.hash.value</code><br/><code>metadata.proof.signature.alg</code><br/><code>metadata.proof.signature.value</code><br/><code>metadata.proof.signature.kid</code><br/><code>metadata.proof.signer_id</code></p>
</section>

<section class="api-card section">
<h2>Error and status model</h2>
<div class="grid-3">
<div class="status-card"><h3>VALID / VERIFIED</h3><p>Proof checks passed.</p></div>
<div class="status-card"><h3>INVALID</h3><p>Proof checks failed.</p></div>
<div class="status-card"><h3>TRANSPORT_ERROR</h3><p>Network/runtime/verifier unavailable.</p></div>
<div class="status-card"><h3>BAD_REQUEST</h3><p>Invalid request shape.</p></div>
<div class="status-card"><h3>UNSUPPORTED_VERB</h3><p>Unsupported capability verb.</p></div>
<div class="status-card"><h3>MISSING_PROOF</h3><p>Receipt missing metadata.proof.</p></div>
<div class="status-card"><h3>HASH_MISMATCH</h3><p>Canonical hash mismatch.</p></div>
<div class="status-card"><h3>SIGNATURE_INVALID</h3><p>Ed25519 signature invalid.</p></div>
</div>
</section>

<section class="api-card section">
<h2>Security / trust boundaries</h2>
<ul>
<li>Runtime signs.</li>
<li>Verifier validates.</li>
<li>MCP bridges.</li>
<li>SDK wraps.</li>
<li>Schemas describe shape.</li>
<li>Schema-valid alone is not verified.</li>
<li>Private keys must never be sent through MCP or public verifier endpoints.</li>
<li>Receipts are only verified when hash and signature checks pass.</li>
</ul>
</section>

<section class="api-card section">
<h2>Developer integration paths</h2>
<div class="grid-2">
<div class="path-card"><h3>Direct HTTP</h3><p>Call runtime endpoints directly.</p></div>
<div class="path-card"><h3>MCP client</h3><p>Use MCP tools and let the bridge forward to runtime.</p></div>
<div class="path-card"><h3>SDK</h3><p>Use <code>@commandlayer/agent-sdk@1.2.0</code>.</p></div>
<div class="path-card"><h3>Manual verifier</h3><p>Paste receipts into <code>/verify.html</code>.</p></div>
</div>
</section>

<section class="api-card section">
<h2>Next steps</h2>
<div class="cta-grid">
<a class="primary" href="/stack-proof-demo.html">View Production Proof</a>
<a href="/capabilities.html">Explore Capabilities</a>
<a href="/docs/wrap-your-agent.html">Wrap Your Agent</a>
<a href="/verify.html">Open Verifier</a>
</div>
</section>
</main>

<footer><div class="container footer-grid"><div><h4>Product</h4><a href="/protocol.html">Protocol</a><a href="/capabilities.html">Capabilities</a><a href="/verify.html">Verifier</a><a href="/runtime.html">Runtime</a><a href="/mcp.html">MCP</a><a href="/claim.html">Claim</a></div><div><h4>Developers</h4><a href="/docs.html">Docs</a><a href="/sdk-records.html">SDK</a><a href="/schemas.html">Schemas</a><a href="/api.html">API</a><a href="https://github.com/commandlayer" target="_blank" rel="noopener">GitHub</a></div><div><h4>Proof</h4><a href="/stack-proof-demo.html">Production Proof</a><a href="/verifyagent.html">VerifyAgent</a><a href="/trust-verification.html">Trust Verification</a><a href="/canonical-receipts.html">Canonical Receipts</a></div></div></footer>
</body>
</html>
Loading