bzzz/docs/BZZZv2B-API_REFERENCE.md

BZZZ API Reference

Version 2.0 - Phase 2B Edition
Complete API reference for BZZZ's unified semantic context publishing platform.

Table of Contents

1. Overview
2. Authentication
3. Agent APIs
4. Decision APIs
5. Crypto APIs
6. Admin APIs
7. DHT APIs
8. Debug APIs
9. WebSocket APIs
10. Error Codes
11. Data Models

Overview

The BZZZ API provides RESTful endpoints for interacting with the distributed semantic context publishing platform. All APIs use JSON for request/response payloads and include comprehensive error handling.

Base URL

http://localhost:8080/api

Content Types

• Request: application/json
• Response: application/json
• WebSocket: application/json messages

Cross-References

• Implementation: api/ package in codebase
• Configuration: CONFIG_REFERENCE.md
• User Guide: USER_MANUAL.md
• Security Model: SECURITY.md

Authentication

BZZZ uses role-based authentication with optional admin authorization for privileged operations.

Role-Based Access

Most APIs automatically use your agent's configured role. No explicit authentication required for standard operations.

Admin Authorization

Admin-only endpoints require the admin authorization header:

Authorization: Admin QmAdminNodeID

Cross-Reference: Admin role management in pkg/config/roles.go:IsAdminRole()

Agent APIs

Endpoints for agent status, configuration, and capabilities.

GET /agent/status

Get current agent status and configuration.

Response:

{
  "node_id": "QmYourNodeID",
  "agent_id": "backend-dev-01", 
  "role": "backend_developer",
  "authority_level": "suggestion",
  "specialization": "code_generation",
  "can_decrypt": ["backend_developer"],
  "is_admin": false,
  "capabilities": ["golang", "docker", "kubernetes"],
  "models": ["ollama/codegemma", "ollama/llama3.1"],
  "active_tasks": 2,
  "max_tasks": 5,
  "uptime_seconds": 3600
}

Cross-Reference: Implementation in main.go:announceAvailability()

GET /agent/capabilities

Get detailed agent capabilities and available models.

Response:

{
  "capabilities": ["code_generation", "debugging", "testing"],
  "models": [
    {
      "name": "ollama/codegemma",
      "type": "code_generation", 
      "available": true,
      "last_used": "2025-01-08T15:30:00Z"
    }
  ],
  "specialization": "code_generation",
  "expertise": ["golang", "microservices", "docker"],
  "reports_to": ["senior_software_architect"],
  "deliverables": ["code", "documentation", "tests"]
}

POST /agent/update-role

Update agent role configuration (requires restart).

Request:

{
  "role": "senior_software_architect",
  "specialization": "architecture",
  "models": ["ollama/llama3.1", "gpt-4"]
}

Response:

{
  "status": "updated",
  "restart_required": true,
  "new_authority_level": "decision"
}

Cross-Reference: Role definitions in pkg/config/roles.go

GET /agent/peers

List connected peers and their roles.

Response:

{
  "connected_peers": [
    {
      "node_id": "QmPeer1",
      "agent_id": "architect-01",
      "role": "senior_software_architect", 
      "authority_level": "decision",
      "last_seen": "2025-01-08T15:29:50Z",
      "available": true,
      "active_tasks": 1
    }
  ],
  "total_peers": 3,
  "admin_peer": "QmAdminPeer"
}

Decision APIs

Endpoints for publishing and querying decisions with automatic encryption.

POST /decisions/architectural

Publish an architectural decision.

Request:

{
  "task": "migrate_to_microservices",
  "decision": "Split monolith into 5 microservices based on domain boundaries", 
  "rationale": "Improve scalability, maintainability, and team autonomy",
  "alternatives": [
    "Keep monolith with better modularization",
    "Partial split into 2 services",
    "Complete rewrite with serverless"
  ],
  "implications": [
    "Increased operational complexity",
    "Better scalability and fault isolation", 
    "Need for service mesh",
    "Distributed transaction challenges"
  ],
  "next_steps": [
    "Define service boundaries", 
    "Plan data migration strategy",
    "Set up CI/CD pipelines",
    "Implement monitoring"
  ]
}

Response:

{
  "ucxl_address": "backend_dev/backend_developer/microservices/migrate_to_microservices/1704672000",
  "encrypted": true,
  "stored_at": "2025-01-08T15:30:00Z",
  "accessible_by": ["backend_developer", "senior_software_architect", "admin"],
  "dht_peers": 3
}

Cross-Reference: Implementation in pkg/ucxl/decision_publisher.go:PublishArchitecturalDecision()

POST /decisions/code

Publish a code implementation decision.

Request:

{
  "task": "implement_user_authentication",
  "decision": "Implemented JWT-based authentication with refresh tokens",
  "files_modified": [
    "internal/auth/jwt.go",
    "internal/middleware/auth.go", 
    "cmd/server/main.go"
  ],
  "lines_changed": 245,
  "test_results": {
    "passed": 18,
    "failed": 1, 
    "skipped": 2,
    "coverage": 87.5,
    "failed_tests": ["TestJWT_ExpiredToken"]
  },
  "dependencies": [
    "github.com/golang-jwt/jwt/v5",
    "golang.org/x/crypto/bcrypt"
  ],
  "language": "go"
}

Response:

{
  "ucxl_address": "backend_dev/backend_developer/auth/implement_user_authentication/1704672000", 
  "encrypted": true,
  "content_type": "decision",
  "size_bytes": 1024,
  "hash": "sha256:abc123...",
  "stored_at": "2025-01-08T15:30:00Z"
}

Cross-Reference: Implementation in pkg/ucxl/decision_publisher.go:PublishCodeDecision()

POST /decisions/system-status

Publish system status and health information.

Request:

{
  "status": "All systems operational",
  "metrics": {
    "uptime_seconds": 86400,
    "active_peers": 4,
    "decisions_published": 25,
    "decisions_retrieved": 12,
    "cache_hit_rate": 0.85,
    "dht_entries": 150,
    "memory_usage_mb": 245.7
  },
  "health_checks": {
    "dht_connected": true,
    "elections_ready": true, 
    "crypto_functional": true,
    "peers_discovered": true,
    "admin_available": true
  }
}

Response:

{
  "ucxl_address": "backend_dev/backend_developer/system/system_status/1704672000",
  "status_recorded": true,
  "alert_level": "normal"
}

GET /decisions/query

Query recent decisions with filtering.

Query Parameters:

• agent: Filter by agent ID
• role: Filter by creator role
• project: Filter by project name
• task: Filter by task name
• content_type: Filter by decision type
• since: ISO timestamp for date filtering
• limit: Maximum results (default: 10, max: 100)

Example:

GET /decisions/query?role=backend_developer&project=auth&limit=5

Response:

{
  "decisions": [
    {
      "address": "backend_dev/backend_developer/auth/implement_jwt/1704672000",
      "creator_role": "backend_developer",
      "content_type": "decision", 
      "timestamp": "2025-01-08T15:30:00Z",
      "size": 1024,
      "encrypted_for": ["backend_developer", "senior_software_architect", "admin"],
      "dht_peers": 3
    }
  ],
  "total_found": 1,
  "query_time_ms": 45
}

Cross-Reference: Implementation in pkg/ucxl/decision_publisher.go:QueryRecentDecisions()

GET /decisions/content/{ucxl_address}

Retrieve and decrypt specific decision content.

Parameters:

• ucxl_address: Full UCXL address of the decision

Example:

GET /decisions/content/backend_dev/backend_developer/auth/implement_jwt/1704672000

Response:

{
  "address": "backend_dev/backend_developer/auth/implement_jwt/1704672000",
  "agent": "backend_dev",
  "role": "backend_developer",
  "project": "auth", 
  "task": "implement_jwt",
  "decision": "Implemented JWT authentication with refresh tokens",
  "context": {
    "decision_type": "code",
    "language": "go",
    "node_id": "QmYourNode"
  },
  "timestamp": "2025-01-08T15:30:00Z",
  "success": true,
  "files_modified": ["auth.go", "middleware.go"],
  "lines_changed": 245,
  "test_results": {
    "passed": 18,
    "failed": 1,
    "coverage": 87.5
  },
  "decrypted_by": "backend_developer"
}

Error Response (403 Forbidden):

{
  "error": "access_denied",
  "message": "Current role cannot decrypt content from role: admin",
  "current_role": "backend_developer",
  "required_authority": "master"
}

Cross-Reference: Implementation in pkg/ucxl/decision_publisher.go:GetDecisionContent()

Crypto APIs

Endpoints for encryption, key management, and cryptographic operations.

GET /crypto/test-age

Test Age encryption functionality.

Response:

{
  "test_passed": true,
  "key_generation": "ok",
  "encryption": "ok", 
  "decryption": "ok",
  "test_content_size": 64,
  "execution_time_ms": 12
}

Cross-Reference: Implementation in pkg/crypto/age_crypto.go:TestAgeEncryption()

GET /crypto/test-shamir

Test Shamir secret sharing functionality.

Response:

{
  "test_passed": true,
  "secret_splitting": "ok",
  "secret_reconstruction": "ok",
  "threshold": 3,
  "total_shares": 5,
  "execution_time_ms": 89
}

Cross-Reference: Implementation in pkg/crypto/shamir.go:TestShamirSecretSharing()

POST /crypto/generate-keys

Generate new Age key pair for role-based encryption.

Response:

{
  "public_key": "age1abcdef1234567890abcdef1234567890abcdef1234567890abcdef12345678",
  "private_key": "AGE-SECRET-KEY-1ABCDEF1234567890ABCDEF1234567890ABCDEF1234567890ABCDEF1234567890",
  "key_type": "X25519",
  "generated_at": "2025-01-08T15:30:00Z"
}

⚠️ Security Warning: Store the private key securely and never share it.

Cross-Reference: Implementation in pkg/crypto/age_crypto.go:GenerateAgeKeyPair()

POST /crypto/validate-keys

Validate Age key format and functionality.

Request:

{
  "public_key": "age1abcdef...",
  "private_key": "AGE-SECRET-KEY-1...",
  "test_encryption": true
}

Response:

{
  "public_key_valid": true,
  "private_key_valid": true,
  "key_pair_matches": true,
  "encryption_test": "passed",
  "key_format": "X25519"
}

Cross-Reference: Implementation in pkg/crypto/age_crypto.go:ValidateAgeKey()

GET /crypto/role-permissions

Get current role's encryption permissions.

Response:

{
  "current_role": "backend_developer",
  "authority_level": "suggestion",
  "can_decrypt": ["backend_developer"],
  "can_be_decrypted_by": [
    "backend_developer",
    "senior_software_architect", 
    "admin"
  ],
  "has_age_keys": true,
  "key_status": "valid"
}

Admin APIs

Administrative endpoints requiring admin authorization.

GET /admin/election-status

Get current election and admin status.

Authorization: Admin required

Response:

{
  "current_admin": "QmAdminNode",
  "is_election_active": false,
  "last_election": "2025-01-08T14:30:00Z",
  "election_reason": "heartbeat_timeout",
  "candidates": [],
  "quorum_size": 3,
  "active_nodes": 5,
  "last_heartbeat": "2025-01-08T15:29:50Z",
  "next_heartbeat": "2025-01-08T15:30:05Z"
}

Cross-Reference: Implementation in pkg/election/election.go:GetElectionStatus()

POST /admin/trigger-election

Manually trigger an admin election.

Authorization: Admin required

Request:

{
  "reason": "manual_trigger",
  "force": false
}

Response:

{
  "election_triggered": true,
  "election_id": "election-1704672000",
  "candidates": [
    {
      "node_id": "QmCandidate1",
      "role": "admin",
      "score": 95.5,
      "capabilities": ["high_uptime", "master_authority"]
    }
  ],
  "expected_completion": "2025-01-08T15:31:00Z"
}

Cross-Reference: Implementation in pkg/election/election.go:TriggerElection()

GET /admin/key-shares

View admin key shares information.

Authorization: Admin required

Response:

{
  "total_shares": 5,
  "threshold": 3,
  "distributed_shares": [
    {
      "node_id": "QmNode1", 
      "share_index": 1,
      "has_share": true,
      "last_validated": "2025-01-08T15:00:00Z"
    },
    {
      "node_id": "QmNode2",
      "share_index": 2, 
      "has_share": true,
      "last_validated": "2025-01-08T15:00:00Z"
    }
  ],
  "reconstruction_possible": true
}

Cross-Reference: Implementation in pkg/crypto/shamir.go:AdminKeyManager

POST /admin/reconstruct-key

Reconstruct admin private key from shares.

Authorization: Admin required

Request:

{
  "shares": [
    {
      "node_id": "QmNode1",
      "index": 1,
      "share": "base64-encoded-share"
    },
    {
      "node_id": "QmNode2", 
      "index": 2,
      "share": "base64-encoded-share"
    },
    {
      "node_id": "QmNode3",
      "index": 3,
      "share": "base64-encoded-share"
    }
  ]
}

Response:

{
  "reconstruction_successful": true,
  "key_reconstructed": true,
  "shares_used": 3,
  "validation_passed": true
}

⚠️ Security Warning: Reconstructed keys contain sensitive admin privileges.

Cross-Reference: Implementation in pkg/crypto/shamir.go:ReconstructAdminKey()

DHT APIs

Endpoints for DHT storage operations and metrics.

GET /dht/metrics

Get DHT storage and performance metrics.

Response:

{
  "stored_items": 25,
  "retrieved_items": 12,
  "cache_hits": 8,
  "cache_misses": 4,
  "cache_hit_rate": 0.67,
  "encryption_ops": 25,
  "decryption_ops": 12,
  "average_store_time_ms": 150,
  "average_retrieve_time_ms": 45,
  "connected_peers": 4,
  "last_update": "2025-01-08T15:30:00Z"
}

Cross-Reference: Implementation in pkg/dht/encrypted_storage.go:GetMetrics()

GET /dht/content/{ucxl_address}

Retrieve raw encrypted content from DHT (admin only).

Authorization: Admin required
Parameters:

• ucxl_address: Full UCXL address

Response:

{
  "address": "backend_dev/backend_developer/auth/jwt/1704672000",
  "encrypted_content": "base64-encoded-encrypted-data",
  "metadata": {
    "creator_role": "backend_developer",
    "encrypted_for": ["backend_developer", "senior_software_architect", "admin"],
    "content_type": "decision",
    "size": 1024,
    "hash": "sha256:abc123...",
    "timestamp": "2025-01-08T15:30:00Z",
    "dht_peers": 3,
    "replication_factor": 3
  }
}

POST /dht/store-raw

Store raw encrypted content in DHT (admin only).

Authorization: Admin required

Request:

{
  "ucxl_address": "admin/admin/system/backup/1704672000",
  "content": "base64-encoded-encrypted-content",
  "creator_role": "admin",
  "content_type": "backup"
}

Response:

{
  "stored": true,
  "dht_key": "/bzzz/ucxl/generated-hash",
  "replication_factor": 3,
  "announced": true
}

Cross-Reference: Implementation in pkg/dht/encrypted_storage.go:StoreUCXLContent()

GET /dht/peers/{ucxl_address}

Discover peers that have specific content.

Parameters:

• ucxl_address: Full UCXL address to discover

Response:

{
  "content_address": "backend_dev/backend_developer/auth/jwt/1704672000",
  "peers_with_content": [
    {
      "peer_id": "QmPeer1",
      "node_id": "Node1", 
      "announced_at": "2025-01-08T15:25:00Z"
    },
    {
      "peer_id": "QmPeer2",
      "node_id": "Node2",
      "announced_at": "2025-01-08T15:26:00Z"
    }
  ],
  "total_peers": 2
}

Cross-Reference: Implementation in pkg/dht/encrypted_storage.go:DiscoverContentPeers()

Debug APIs

Development and debugging endpoints.

GET /debug/status

Get comprehensive system status for debugging.

Response:

{
  "system": {
    "version": "2.0",
    "uptime_seconds": 3600,
    "go_version": "go1.23.0",
    "memory_usage_mb": 156.7
  },
  "node": {
    "id": "QmYourNode",
    "addresses": ["/ip4/192.168.1.100/tcp/4001"],
    "connected_peers": 4
  },
  "agent": {
    "id": "backend-dev-01",
    "role": "backend_developer",
    "authority": "suggestion",
    "active_tasks": 2,
    "max_tasks": 5
  },
  "dht": {
    "connected": true,
    "stored_items": 25,
    "bootstrap_peers": 2
  },
  "crypto": {
    "age_functional": true,
    "shamir_functional": true,
    "keys_configured": true
  },
  "admin": {
    "current_admin": "QmAdminPeer",
    "is_admin": false,
    "election_active": false,
    "last_heartbeat": "2025-01-08T15:29:50Z"
  }
}

GET /debug/recent-decisions

Get recent decisions with full debug information.

Query Parameters:

• limit: Maximum results (default: 5, max: 20)

Response:

{
  "decisions": [
    {
      "address": "backend_dev/backend_developer/auth/jwt/1704672000",
      "metadata": {
        "creator_role": "backend_developer",
        "content_type": "decision",
        "size": 1024,
        "timestamp": "2025-01-08T15:30:00Z"
      },
      "storage": {
        "dht_key": "/bzzz/ucxl/abc123...",
        "cached": true,
        "cache_expires": "2025-01-08T15:40:00Z",
        "replication_peers": 3
      },
      "access": {
        "can_decrypt": true,
        "encrypted_for": ["backend_developer", "senior_software_architect", "admin"]
      }
    }
  ],
  "debug_info": {
    "query_time_ms": 25,
    "cache_hits": 1,
    "dht_lookups": 0
  }
}

POST /debug/test-e2e

Run end-to-end system test.

Response:

{
  "test_passed": true,
  "stages": {
    "age_encryption": "passed",
    "shamir_reconstruction": "passed", 
    "decision_publishing": "passed",
    "dht_storage": "passed",
    "content_retrieval": "passed",
    "decryption": "passed"
  },
  "execution_time_ms": 1250,
  "decisions_created": 3,
  "content_verified": 3
}

Cross-Reference: Implementation in main.go:testEndToEndDecisionFlow()

WebSocket APIs

Real-time event streaming via WebSocket connections.

WebSocket /ws/events

Stream real-time system events.

Connection:

const ws = new WebSocket('ws://localhost:8080/ws/events');

Event Types:

Decision Published

{
  "type": "decision_published",
  "timestamp": "2025-01-08T15:30:00Z",
  "data": {
    "address": "backend_dev/backend_developer/auth/jwt/1704672000",
    "creator_role": "backend_developer", 
    "content_type": "decision",
    "can_decrypt": true
  }
}

Admin Changed

{
  "type": "admin_changed",
  "timestamp": "2025-01-08T15:30:00Z", 
  "data": {
    "old_admin": "QmOldAdmin",
    "new_admin": "QmNewAdmin",
    "election_reason": "heartbeat_timeout"
  }
}

Peer Connected/Disconnected

{
  "type": "peer_connected",
  "timestamp": "2025-01-08T15:30:00Z",
  "data": {
    "peer_id": "QmNewPeer",
    "agent_id": "architect-02",
    "role": "senior_software_architect"
  }
}

WebSocket /ws/decisions/{role}

Stream decisions for specific role.

Connection:

const ws = new WebSocket('ws://localhost:8080/ws/decisions/backend_developer');

Events: Only decision events for the specified role.

Error Codes

Standard HTTP error codes with BZZZ-specific error details.

400 Bad Request

{
  "error": "bad_request",
  "message": "Invalid UCXL address format", 
  "details": {
    "provided": "invalid/address", 
    "expected_format": "agent/role/project/task/node"
  }
}

401 Unauthorized

{
  "error": "unauthorized",
  "message": "Admin authorization required",
  "required_header": "Authorization: Admin QmNodeID"
}

403 Forbidden

{
  "error": "access_denied",
  "message": "Current role cannot decrypt content from role: admin",
  "current_role": "backend_developer",
  "required_authority": "master"
}

404 Not Found

{
  "error": "not_found",
  "message": "UCXL content not found in DHT",
  "address": "backend_dev/backend_developer/missing/task/1704672000",
  "searched_peers": 4
}

500 Internal Server Error

{
  "error": "internal_error",
  "message": "Age encryption failed", 
  "details": {
    "operation": "encrypt_for_role",
    "role": "backend_developer",
    "key_status": "invalid"
  },
  "request_id": "req-abc123"
}

503 Service Unavailable

{
  "error": "service_unavailable",
  "message": "DHT not connected",
  "retry_after": 30,
  "status": {
    "dht_connected": false,
    "bootstrap_peers": 0
  }
}

Data Models

Core data structures used in API responses.

AgentStatus

interface AgentStatus {
  node_id: string;           // P2P node identifier
  agent_id: string;          // Agent identifier  
  role: string;              // Current role name
  authority_level: string;   // Authority level (master, decision, suggestion, read_only)
  specialization: string;    // Agent specialization
  can_decrypt: string[];     // Roles this agent can decrypt
  is_admin: boolean;         // Whether this node is admin
  capabilities: string[];    // Agent capabilities
  models: string[];          // Available AI models
  active_tasks: number;      // Current active tasks
  max_tasks: number;         // Maximum concurrent tasks
  uptime_seconds: number;    // Uptime in seconds
}

TaskDecision

interface TaskDecision {
  agent: string;                    // Creator agent ID
  role: string;                     // Creator role
  project: string;                  // Project name
  task: string;                     // Task name
  decision: string;                 // Decision description
  context: Record<string, any>;     // Additional context
  timestamp: string;                // ISO timestamp
  success: boolean;                 // Whether task succeeded
  error_message?: string;           // Error if failed
  files_modified?: string[];        // Modified files
  lines_changed?: number;           // Lines of code changed
  test_results?: TestResults;       // Test execution results
  dependencies?: string[];          // Dependencies added/modified
  next_steps?: string[];            // Recommended next steps
}

TestResults

interface TestResults {
  passed: number;           // Passed tests
  failed: number;           // Failed tests  
  skipped: number;          // Skipped tests
  coverage?: number;        // Code coverage percentage
  failed_tests?: string[];  // Names of failed tests
}

UCXLMetadata

interface UCXLMetadata {
  address: string;           // Full UCXL address
  creator_role: string;      // Role that created content
  encrypted_for: string[];   // Roles that can decrypt
  content_type: string;      // Content type (decision, status, etc)
  timestamp: string;         // Creation timestamp
  size: number;              // Content size in bytes
  hash: string;              // SHA256 hash of encrypted content
  dht_peers: string[];       // Peers that have this content
  replication_factor: number; // Number of peer replicas
}

ElectionStatus

interface ElectionStatus {
  current_admin: string;          // Current admin node ID
  is_election_active: boolean;    // Whether election is running
  last_election: string;          // Last election timestamp
  election_reason: string;        // Reason for last election
  candidates: ElectionCandidate[]; // Current candidates
  quorum_size: number;            // Required quorum size
  active_nodes: number;           // Currently active nodes
  last_heartbeat: string;         // Last admin heartbeat
  next_heartbeat: string;         // Next expected heartbeat
}

ElectionCandidate

interface ElectionCandidate {
  node_id: string;           // Candidate node ID
  role: string;              // Candidate role
  score: number;             // Election score
  capabilities: string[];    // Candidate capabilities
  uptime_seconds: number;    // Candidate uptime
  authority_level: string;   // Authority level
}

---

Cross-References

• User Manual: USER_MANUAL.md
• Developer Guide: DEVELOPER.md
• Configuration: CONFIG_REFERENCE.md
• Security Model: SECURITY.md
• Implementation: Source code in api/, pkg/*/ packages

BZZZ API Reference v2.0 - Complete API documentation for Phase 2B unified architecture with Age encryption and DHT storage.