From fe407abc5dfc01b81d9c171c627777ba7aa52c09 Mon Sep 17 00:00:00 2001 From: Greg Soucy Date: Thu, 21 May 2026 16:02:25 -0400 Subject: [PATCH] Rebuild API reference page with full developer surface docs --- public/api.html | 232 ++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 227 insertions(+), 5 deletions(-) diff --git a/public/api.html b/public/api.html index 2d8d7e8..ee3eb0a 100644 --- a/public/api.html +++ b/public/api.html @@ -1,5 +1,227 @@ -CommandLayer API Index

API Index

Response states

Example runtime sign

curl -X POST https://runtime.commandlayer.org/trust-verification/sign/v1.0.0 \
-  -H "Content-Type: application/json" \
-  -d '{"payload":{"subject":"demo"}}'

Example runtime verify

curl -X POST https://runtime.commandlayer.org/verify \
-  -H "Content-Type: application/json" \
-  -d '{"receipt":{}}'

Note: website /api/verify route behavior should be treated cautiously unless separately validated for canonical production semantics.

\ No newline at end of file + + + + + + CommandLayer API Reference | Infrastructure Surface Map + + + + + + + + + + + +
+
+
API Reference
+

API surfaces for verifiable agent actions.

+

Use CommandLayer runtime, verifier, MCP, and website verifier surfaces to issue signed receipts, verify proof, and integrate verifiable agent workflows.

+
+ Try Verifier + View Production Proof +
+
Production proof status: 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 runtime.commandlayer.eth with kid=vC4WbcNoq2znSCiQ. Canonical proof is metadata.proof.canonicalization=json.sorted_keys.v1, metadata.proof.hash.alg=SHA-256, metadata.proof.signature.alg=Ed25519.
+
+
+ +
+
+

API surface overview

+

CommandLayer APIs expose runtime signing, receipt verification, MCP transport, and website verifier surfaces for verifiable agent actions.

+
+

Runtime API

Production execution/signing and verification surface.

 +

MCP Transport

Bridge for MCP clients. Transport changes; proof model does not.

 +

Trust Verification

Canonical Trust Verification v1 endpoints and verbs.

 +

Website Verifier

Human-facing verification UI and public verifier surfaces.

 +

SDK

Developer wrapper for receipts and verifier calls.

 +

Schemas

Request/receipt/proof structure.

 +
+
+ +
+

Runtime endpoints

+
+
GET https://runtime.commandlayer.org/health
+
POST https://runtime.commandlayer.org/verify
+
POST https://runtime.commandlayer.org/trust-verification/{verb}/v1.0.0
+
+

Supported Trust Verification verbs

+

sign, attest, authorize, approve, reject, permit, grant, authenticate, endorse

+
Important: verify is the verifier action/surface, not a signer endpoint.
+
+ +
+

Runtime sign example

+ 
curl -X POST https://runtime.commandlayer.org/trust-verification/sign/v1.0.0 \
+  -H "content-type: application/json" \
+  -d '{"payload":{"message":"hello from CommandLayer"}}'
+

Expected response shape

+ 
{
+  "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"
+      }
+    }
+  }
+}
+
+ +
+

Runtime verify example

+ 
curl -X POST https://runtime.commandlayer.org/verify \
+  -H "content-type: application/json" \
+  -d '{"receipt":{...}}'
+
+

VALID / VERIFIED

Hash and signature checks passed.

+

INVALID

Proof failed, payload changed, unsupported proof, wrong signer/key, or missing proof.

+

TRANSPORT_ERROR

Verifier/runtime unavailable or request failed.

+
+
+ +
+

MCP endpoint section

+
+
GET https://mcp.commandlayer.org/health
+
POST https://mcp.commandlayer.org/mcp
+
+
Important: GET /mcp is not expected to work. /mcp is POST-only MCP transport.
+

MCP tools

+

clas.trust-verification.verify, clas.trust-verification.sign, clas.trust-verification.attest, clas.trust-verification.authorize, clas.trust-verification.approve, clas.trust-verification.reject, clas.trust-verification.permit, clas.trust-verification.grant, clas.trust-verification.authenticate, clas.trust-verification.endorse

+
Trust boundary: 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.
+
+ +
+

Website verifier surfaces

+
    +
  • /verify.html — Interactive manual verifier.
    • +
  • /api/verify — Website verifier API surface; treat as a website-facing verifier surface unless separately validated for parity with runtime /verify.
    • +
  • /api/agents/verifyagent — VerifyAgent metadata/API alias surface if present.
    • +
+
Warning: Do not treat /api/verify as the canonical production verifier unless tests prove parity with runtime /verify.
+
+ +
+

Request/response conventions

+

Content-Type: application/json

+
+
+

Input for signer endpoints

+ 
{
+  "payload": {}
+}
+
+
+

Input for verifier endpoints

+ 
{
+  "receipt": {}
+}
+
+
+

Canonical proof fields

+

metadata.proof.canonicalization
metadata.proof.hash.alg
metadata.proof.hash.value
metadata.proof.signature.alg
metadata.proof.signature.value
metadata.proof.signature.kid
metadata.proof.signer_id

+
+ +
+

Error and status model

+
+

VALID / VERIFIED

Proof checks passed.

+

INVALID

Proof checks failed.

+

TRANSPORT_ERROR

Network/runtime/verifier unavailable.

+

BAD_REQUEST

Invalid request shape.

+

UNSUPPORTED_VERB

Unsupported capability verb.

+

MISSING_PROOF

Receipt missing metadata.proof.

+

HASH_MISMATCH

Canonical hash mismatch.

+

SIGNATURE_INVALID

Ed25519 signature invalid.

+
+
+ +
+

Security / trust boundaries

+
    +
  • Runtime signs.
    • +
  • Verifier validates.
    • +
  • MCP bridges.
    • +
  • SDK wraps.
    • +
  • Schemas describe shape.
    • +
  • Schema-valid alone is not verified.
    • +
  • Private keys must never be sent through MCP or public verifier endpoints.
    • +
  • Receipts are only verified when hash and signature checks pass.
    • +
+
+ +
+

Developer integration paths

+
+

Direct HTTP

Call runtime endpoints directly.

+

MCP client

Use MCP tools and let the bridge forward to runtime.

+

SDK

Use @commandlayer/agent-sdk@1.2.0.

+

Manual verifier

Paste receipts into /verify.html.

+
+
+ +
+

Next steps

+
+ View Production Proof + Explore Capabilities + Wrap Your Agent + Open Verifier +
+
+
+ + + +