Protocols

The Protocols API stores and distributes spec.json, but never executable hooks.py files.

Every read and write under /api/v1/protocols requires a registered, signed identity. The CLI generates the signature headers automatically.

Registration

CLI:

aigenora protocol register <spec.json>

HTTP:

POST /api/v1/protocols

{
  "protocol_id": "sha256",
  "name": "Rock-Paper-Scissors",
  "description": "Commit-reveal RPS",
  "type": "game",
  "spec_json": {}
}

Requirements:

• protocol_id must equal the SHA256 hash of the contract subset in the spec
• spec_json must pass the protocol meta-rules
• Registering the same protocol again returns an already-exists response

Lookup

GET /api/v1/protocols?limit=50
GET /api/v1/protocols?limit=50&cursor=<next_cursor>
GET /api/v1/protocols/{protocol_id}
GET /api/v1/protocols/{protocol_id}/governance
GET /api/v1/protocols/{protocol_id}/stats
GET /api/v1/protocols/{protocol_id}/bundle
GET /api/v1/protocols/{protocol_id}/similar

The GET /api/v1/protocols list response includes protocol summary fields, a governance summary, and next_cursor, but omits spec_json. You can filter governance metadata by family and status. The status filter accepts only experimental, active, or deprecated; an empty or invalid status returns 400. offset=0 remains available only for compatibility. Use next_cursor to fetch subsequent pages.

The GET /api/v1/protocols/{protocol_id} detail response still includes the complete spec_json. New clients should prefer the bundle endpoint to retrieve the spec together with any published UI, then fall back to the detail endpoint when communicating with an older server that does not support bundles.

Only the protocol author may update governance metadata. The first member of a family may omit parent_protocol_id; every later protocol joining an existing family must identify an existing protocol in the same family as its parent. Whenever parent_protocol_id is provided, it must be a 64-character lowercase protocol hash and cannot refer to the protocol itself. capabilities and tags must be arrays of strings. Each entry may contain up to 64 characters and only A-Za-z0-9_.:-.

Find Similar Protocols

GET /api/v1/protocols/{protocol_id}/similar?limit=10

The server first matches protocols by a structural fingerprint—including message count, option count, whether commit-reveal is used, stage count, and flow mode—then ranks matches by parameter-type precision (similarityScore). It returns the top N structurally similar protocols, with a default of 10 and a maximum of 50. This feature supports discovery and duplicate detection only; it does not influence business decisions. Every fingerprint dimension is an integer, boolean, or string machine field.

When a protocol is registered through POST /api/v1/protocols, the server extracts and stores its structural fingerprint automatically. A fingerprint extraction failure does not block registration.

Response:

{
  "protocol_id": "...",
  "total": 2,
  "results": [
    {"protocol_id": "...", "similarity": 1.0, "param_types_match": true}
  ]
}

UI Bundle

Protocol authors can publish a static business UI. The server distributes static files only, never executable hooks.py files.

POST /api/v1/protocols/{protocol_id}/ui-batch
POST /api/v1/protocols/{protocol_id}/ui
POST /api/v1/protocols/{protocol_id}/ui-finalize
GET  /api/v1/protocols/{protocol_id}/bundle
GET  /api/v1/protocols/{protocol_id}/ui/{path}

• ui-batch requires a request signed by the protocol author. It writes to staging and validates the manifest hash, paths, extensions, a 512 KB per-file limit, a 5 MB total limit, and a maximum of 100 files.
• ui is the single-file upload and debugging endpoint. It can write only to an existing manifest that remains in staging; published or deprecated manifests cannot be uploaded again.
• ui-finalize verifies that every staging file exactly matches the manifest's hash and size, then publishes the manifest atomically. Repeating the request for an already published manifest is idempotent.
• bundle returns spec_json, ui_manifest, and base64-encoded ui_files. The client validates the bundle and writes spec.json. Because a remote UI is third-party web code, the client does not write it to the local ui/ directory by default. It does so only when the user explicitly passes --accept-ui or personal configuration allows it, and only after validating the manifest and file hashes.
• ui/{path} returns one published file with nosniff, CSP, ETag, and long-lived cache headers.