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](#overview)
2. [Authentication](#authentication)
3. [Agent APIs](#agent-apis)
4. [Decision APIs](#decision-apis)
5. [Crypto APIs](#crypto-apis)
6. [Admin APIs](#admin-apis)
7. [DHT APIs](#dht-apis)
8. [Debug APIs](#debug-apis)
9. [WebSocket APIs](#websocket-apis)
10. [Error Codes](#error-codes)
11. [Data Models](#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](CONFIG_REFERENCE.md)
- **User Guide**: [USER_MANUAL.md](USER_MANUAL.md#api-usage)
- **Security Model**: [SECURITY.md](SECURITY.md#api-security)

## 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:
```http
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**:
```json
{
  "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**:
```json
{
  "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**:
```json
{
  "role": "senior_software_architect",
  "specialization": "architecture",
  "models": ["ollama/llama3.1", "gpt-4"]
}
```

**Response**:
```json
{
  "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**:
```json
{
  "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**:
```json
{
  "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**:
```json
{
  "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**:
```json
{
  "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**:
```json
{
  "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**:
```json
{
  "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**:
```json
{
  "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**:
```json
{
  "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**:
```json
{
  "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):
```json
{
  "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**:
```json
{
  "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**:
```json
{
  "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**:
```json
{
  "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**:
```json
{
  "public_key": "age1abcdef...",
  "private_key": "AGE-SECRET-KEY-1...",
  "test_encryption": true
}
```

**Response**:
```json
{
  "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**:
```json
{
  "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**:
```json
{
  "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**:
```json
{
  "reason": "manual_trigger",
  "force": false
}
```

**Response**:
```json
{
  "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**:
```json
{
  "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**:
```json
{
  "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**:
```json
{
  "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**:
```json
{
  "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**:
```json
{
  "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**:
```json
{
  "ucxl_address": "admin/admin/system/backup/1704672000",
  "content": "base64-encoded-encrypted-content",
  "creator_role": "admin",
  "content_type": "backup"
}
```

**Response**:
```json
{
  "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**:
```json
{
  "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**:
```json
{
  "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**:
```json
{
  "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**:
```json
{
  "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**: 
```javascript
const ws = new WebSocket('ws://localhost:8080/ws/events');
```

**Event Types**:

#### Decision Published
```json
{
  "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
```json
{
  "type": "admin_changed",
  "timestamp": "2025-01-08T15:30:00Z", 
  "data": {
    "old_admin": "QmOldAdmin",
    "new_admin": "QmNewAdmin",
    "election_reason": "heartbeat_timeout"
  }
}
```

#### Peer Connected/Disconnected
```json
{
  "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**:
```javascript
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
```json
{
  "error": "bad_request",
  "message": "Invalid UCXL address format", 
  "details": {
    "provided": "invalid/address", 
    "expected_format": "agent/role/project/task/node"
  }
}
```

### 401 Unauthorized
```json
{
  "error": "unauthorized",
  "message": "Admin authorization required",
  "required_header": "Authorization: Admin QmNodeID"
}
```

### 403 Forbidden
```json
{
  "error": "access_denied",
  "message": "Current role cannot decrypt content from role: admin",
  "current_role": "backend_developer",
  "required_authority": "master"
}
```

### 404 Not Found
```json
{
  "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
```json
{
  "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
```json
{
  "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
```typescript
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
```typescript
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
```typescript
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
```typescript
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
```typescript
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
```typescript
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](USER_MANUAL.md)
- **Developer Guide**: [DEVELOPER.md](DEVELOPER.md)  
- **Configuration**: [CONFIG_REFERENCE.md](CONFIG_REFERENCE.md)
- **Security Model**: [SECURITY.md](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.