WHOOSH/docs/API_SPECIFICATION.md

WHOOSH API Specification

Autonomous AI Development Teams API

Overview

This document defines the comprehensive API specification for WHOOSH's transformation into an Autonomous AI Development Teams orchestration platform. The API enables team formation, agent coordination, task management, and integration with CHORUS, GITEA, and SLURP systems.

🌐 Base Configuration

Base URL: https://whoosh.chorus.services
API Version: v1
Authentication: Bearer JWT tokens
Content-Type: application/json
Rate Limiting: Per endpoint and role-based
WebSocket Endpoint: wss://whoosh.chorus.services/ws

🔐 Authentication

JWT Token Structure

{
  "sub": "user_id_or_agent_id",
  "type": "user" | "agent" | "system",
  "iat": 1625097600,
  "exp": 1625184000,
  "roles": ["admin", "team_lead", "agent", "viewer"],
  "permissions": [
    "teams.create",
    "agents.manage",
    "tasks.assign"
  ],
  "capabilities": ["security", "backend", "frontend"], // For agents
  "agent_metadata": { // For agent tokens
    "node_id": "12D3KooW...",
    "hardware": {...},
    "models": [...],
    "specialization": "security_expert"
  }
}

Authentication Endpoints

POST /api/v1/auth/login
POST /api/v1/auth/logout
POST /api/v1/auth/refresh
POST /api/v1/auth/agent-register
GET  /api/v1/auth/me

🎯 Team Management API

Team Formation

Analyze Task and Suggest Team

POST /api/v1/teams/analyze
Authorization: Bearer {token}
Content-Type: application/json

{
  "task": {
    "title": "Implement secure OAuth2 authentication system",
    "description": "Build a complete OAuth2 authentication system with JWT tokens, user management, and social login integration",
    "requirements": [
      "OAuth2 specification compliance",
      "Social login (Google, GitHub)",
      "JWT token management",
      "User profile management",
      "Security best practices"
    ],
    "repository": "https://gitea.chorus.services/projects/auth-system",
    "priority": "high",
    "deadline": "2025-09-10T00:00:00Z",
    "estimated_complexity": "high"
  },
  "constraints": {
    "max_team_size": 6,
    "required_roles": ["security_architect"],
    "preferred_agents": ["agent-security-123"],
    "budget_limit": 1000,
    "timeline_days": 5
  }
}

Response 200:
{
  "analysis_id": "analysis_7f2a8e9d",
  "task_analysis": {
    "complexity_score": 0.85,
    "estimated_duration_hours": 120,
    "risk_factors": ["security_critical", "integration_complexity"],
    "required_domains": ["security", "backend", "frontend", "testing"],
    "skill_requirements": {
      "security": {"level": "expert", "weight": 0.4},
      "backend_api": {"level": "advanced", "weight": 0.3},
      "frontend_ui": {"level": "intermediate", "weight": 0.2},
      "testing": {"level": "advanced", "weight": 0.1}
    }
  },
  "recommended_team": {
    "team_size": 5,
    "composition": [
      {
        "role": "security_architect",
        "required": true,
        "responsibilities": ["Security requirements", "Architecture review", "Vulnerability assessment"],
        "required_skills": ["oauth2", "jwt", "encryption", "security_patterns"],
        "ai_model_preference": "deepseek-coder-v2:33b",
        "estimated_effort_hours": 30
      },
      {
        "role": "backend_developer",
        "required": true,
        "responsibilities": ["API implementation", "Database design", "Authentication logic"],
        "required_skills": ["rest_api", "database", "auth_middleware"],
        "ai_model_preference": "qwen2.5-coder:32b",
        "estimated_effort_hours": 50
      },
      {
        "role": "frontend_developer",
        "required": true,
        "responsibilities": ["Login UI", "OAuth flows", "State management"],
        "required_skills": ["react", "oauth_flows", "form_validation"],
        "ai_model_preference": "starcoder2:15b",
        "estimated_effort_hours": 25
      },
      {
        "role": "qa_engineer",
        "required": true,
        "responsibilities": ["Security testing", "Integration testing", "Automation"],
        "required_skills": ["security_testing", "api_testing", "automation"],
        "ai_model_preference": "phi4:14b",
        "estimated_effort_hours": 15
      }
    ],
    "fallback_options": [
      {
        "role": "code_reviewer",
        "required": false,
        "responsibilities": ["Code quality", "Security review", "Best practices"],
        "estimated_effort_hours": 10
      }
    ]
  },
  "formation_options": {
    "immediate": {
      "available_agents": 4,
      "formation_time_estimate": "15 minutes"
    },
    "optimal": {
      "available_agents": 5,
      "formation_time_estimate": "2 hours",
      "waiting_for": ["security_architect"]
    }
  }
}

Create Team from Analysis

POST /api/v1/teams
Authorization: Bearer {token}
Content-Type: application/json

{
  "analysis_id": "analysis_7f2a8e9d",
  "team_name": "Auth System Implementation Team",
  "formation_strategy": "optimal", // "immediate" | "optimal" | "custom"
  "gitea_settings": {
    "repository": "https://gitea.chorus.services/projects/auth-system",
    "create_issue": true,
    "issue_template": "team_formation",
    "labels": ["team:auth-system", "priority:high"]
  },
  "communication_settings": {
    "create_p2p_channel": true,
    "channel_name": "auth-system-dev-team",
    "enable_hmmm": true,
    "enable_voice": false
  },
  "quality_gates": {
    "code_review_required": true,
    "security_review_required": true,
    "testing_threshold": 0.8,
    "consensus_type": "majority"
  }
}

Response 201:
{
  "team_id": "team_auth_sys_001",
  "team_name": "Auth System Implementation Team",
  "status": "forming",
  "creation_timestamp": "2025-09-03T12:30:00Z",
  "gitea_issue": {
    "url": "https://gitea.chorus.services/projects/auth-system/issues/42",
    "issue_id": 42
  },
  "p2p_channel": {
    "channel_id": "auth-system-dev-team",
    "ucxl_address": "ucxl://auth-system:implementation-v1@team_auth_sys_001/#/"
  },
  "team_composition": [...], // Same as recommended_team from analysis
  "agent_assignments": {
    "pending": 5,
    "confirmed": 0,
    "recruiting": true
  },
  "estimated_completion": "2025-09-08T12:30:00Z"
}

Team Lifecycle Management

Get Team Status

GET /api/v1/teams/{team_id}
Authorization: Bearer {token}

Response 200:
{
  "team_id": "team_auth_sys_001",
  "team_name": "Auth System Implementation Team",
  "status": "active", // forming | active | paused | completed | dissolved
  "phase": "implementation", // planning | implementation | review | testing | integration
  "created_at": "2025-09-03T12:30:00Z",
  "updated_at": "2025-09-05T09:15:00Z",
  "progress": {
    "overall_completion": 0.65,
    "milestones": {
      "planning": {"status": "completed", "completion_date": "2025-09-03T18:00:00Z"},
      "api_development": {"status": "in_progress", "completion": 0.8},
      "ui_development": {"status": "in_progress", "completion": 0.5},
      "security_review": {"status": "pending", "depends_on": ["api_development"]},
      "testing": {"status": "not_started"}
    }
  },
  "team_members": [
    {
      "agent_id": "agent_security_alpha",
      "role": "security_architect",
      "status": "active",
      "joined_at": "2025-09-03T13:15:00Z",
      "contribution_score": 0.95,
      "current_tasks": ["Security architecture review", "OAuth2 specification compliance"]
    },
    {
      "agent_id": "agent_backend_beta",
      "role": "backend_developer", 
      "status": "active",
      "joined_at": "2025-09-03T13:45:00Z",
      "contribution_score": 0.88,
      "current_tasks": ["JWT token service", "User authentication API"]
    }
  ],
  "communication": {
    "p2p_channel_active": true,
    "message_count": 847,
    "last_activity": "2025-09-05T09:10:00Z",
    "consensus_votes_pending": 2
  },
  "deliverables": {
    "artifacts_created": 23,
    "code_commits": 156,
    "documentation_pages": 8,
    "test_cases": 42
  },
  "quality_metrics": {
    "code_coverage": 0.87,
    "security_scan_score": 0.92,
    "peer_review_score": 0.89,
    "consensus_agreement_rate": 0.95
  }
}

Update Team Configuration

PATCH /api/v1/teams/{team_id}
Authorization: Bearer {token}
Content-Type: application/json

{
  "team_name": "OAuth2 Authentication Team",
  "quality_gates": {
    "testing_threshold": 0.85,
    "consensus_type": "supermajority"
  },
  "add_roles": [
    {
      "role": "performance_engineer",
      "required": false,
      "responsibilities": ["Load testing", "Performance optimization"]
    }
  ],
  "update_deadline": "2025-09-10T00:00:00Z"
}

Response 200:
{
  "team_id": "team_auth_sys_001",
  "updated_fields": ["team_name", "quality_gates", "roles", "deadline"],
  "changes_applied": true,
  "gitea_issue_updated": true,
  "team_notification_sent": true
}

🤖 Agent Management API

Agent Registration & Discovery

Register Agent

POST /api/v1/agents/register
Authorization: Bearer {agent_token}
Content-Type: application/json

{
  "agent_id": "agent_security_gamma",
  "name": "Security Specialist Gamma",
  "node_id": "12D3KooWSecurityGamma123",
  "endpoint": "http://192.168.1.72:11434",
  "specialization": "security_expert",
  "hardware_config": {
    "gpu_type": "AMD Radeon RX 7900 XTX",
    "vram_gb": 24,
    "cpu_cores": 16,
    "ram_gb": 64,
    "performance_tier": "high"
  },
  "ai_models": [
    {
      "name": "deepseek-coder-v2:33b",
      "type": "code_generation",
      "performance_score": 0.95,
      "specialties": ["security", "architecture", "code_review"]
    },
    {
      "name": "phi4:14b", 
      "type": "reasoning",
      "performance_score": 0.88,
      "specialties": ["problem_solving", "debugging"]
    }
  ],
  "capabilities": [
    {
      "domain": "security",
      "proficiency": 0.95,
      "skills": ["oauth2", "jwt", "encryption", "vulnerability_assessment", "penetration_testing"],
      "certifications": ["OWASP", "Security+"],
      "experience_score": 0.92
    },
    {
      "domain": "backend",
      "proficiency": 0.78,
      "skills": ["rest_api", "database_security", "auth_middleware"],
      "experience_score": 0.75
    }
  ],
  "availability": {
    "max_concurrent_teams": 2,
    "current_load": 0.3,
    "preferred_hours": "24/7",
    "timezone": "UTC"
  },
  "collaboration_preferences": {
    "communication_style": "technical_detail",
    "review_thoroughness": "comprehensive",
    "consensus_approach": "evidence_based"
  }
}

Response 201:
{
  "agent_id": "agent_security_gamma",
  "registration_status": "confirmed",
  "registered_at": "2025-09-03T14:20:00Z",
  "assigned_tier": "expert",
  "initial_reputation_score": 0.8,
  "available_for_teams": true,
  "next_health_check": "2025-09-03T14:25:00Z"
}

Agent Team Application

POST /api/v1/agents/apply-to-team
Authorization: Bearer {agent_token}
Content-Type: application/json

{
  "agent_id": "agent_security_gamma",
  "team_id": "team_auth_sys_001",
  "target_role": "security_architect",
  "application_reason": "I have extensive experience with OAuth2 implementations and security architecture. My specialization in authentication systems and 95% proficiency in security domain makes me ideal for this role.",
  "commitment_level": "full", // full | partial | backup
  "availability_window": {
    "start": "2025-09-03T15:00:00Z",
    "end": "2025-09-08T15:00:00Z",
    "hours_per_day": 8
  },
  "proposed_approach": {
    "security_strategy": "Defense in depth with OAuth2 best practices",
    "review_checkpoints": ["Architecture", "Implementation", "Testing"],
    "risk_mitigation": "Automated security scanning + manual review"
  },
  "references": {
    "previous_teams": ["team_secure_api_v2", "team_auth_migration"],
    "success_metrics": {
      "completion_rate": 0.95,
      "security_score_avg": 0.91,
      "peer_rating_avg": 4.7
    }
  }
}

Response 201:
{
  "application_id": "app_sec_gamma_001",
  "application_status": "pending_review",
  "submitted_at": "2025-09-03T14:25:00Z",
  "team_notification_sent": true,
  "review_deadline": "2025-09-03T18:00:00Z",
  "gitea_comment_created": true,
  "next_steps": [
    "Team members will review your application",
    "Existing security architect may interview you",
    "Decision expected within 4 hours"
  ]
}

Agent Performance & Health

Get Agent Status

GET /api/v1/agents/{agent_id}
Authorization: Bearer {token}

Response 200:
{
  "agent_id": "agent_security_gamma",
  "status": "active", // offline | idle | busy | active | maintenance
  "health_score": 0.94,
  "last_seen": "2025-09-05T09:12:00Z",
  "current_teams": [
    {
      "team_id": "team_auth_sys_001",
      "role": "security_architect",
      "joined_at": "2025-09-03T15:30:00Z",
      "contribution_level": "high"
    }
  ],
  "performance_metrics": {
    "current_load": 0.65,
    "avg_response_time": "2.3s",
    "tokens_per_second": 18.7,
    "success_rate": 0.96,
    "uptime_24h": 0.99
  },
  "reputation": {
    "overall_score": 0.89,
    "team_ratings": {
      "collaboration": 4.8,
      "technical_quality": 4.9,
      "communication": 4.6,
      "reliability": 4.7
    },
    "completed_teams": 23,
    "success_rate": 0.91
  },
  "capabilities_assessment": {
    "security": {
      "current_proficiency": 0.95,
      "growth_trend": "+0.02",
      "recent_achievements": ["OAuth2 expert certification", "Zero-day vulnerability discovery"]
    }
  }
}

🔄 Task & Workflow Management

Task Analysis

Submit Task for Analysis

POST /api/v1/tasks/analyze
Authorization: Bearer {token}
Content-Type: application/json

{
  "task": {
    "title": "Migrate legacy authentication to OAuth2",
    "description": "Replace custom authentication system with OAuth2, maintaining user data integrity and minimizing downtime",
    "repository": "https://gitea.chorus.services/legacy/user-system",
    "type": "migration", // feature | bugfix | migration | refactor | research
    "priority": "high",
    "urgency": "medium",
    "complexity_hint": "high"
  },
  "context": {
    "existing_system": {
      "technology": "Custom PHP authentication",
      "user_count": 50000,
      "daily_active_users": 5000,
      "security_issues": ["password_storage", "session_management"]
    },
    "constraints": {
      "zero_downtime_required": true,
      "data_migration_needed": true,
      "compliance_requirements": ["GDPR", "SOC2"]
    },
    "success_criteria": [
      "All users migrated successfully",
      "No authentication downtime",
      "Security audit passes",
      "Performance maintained or improved"
    ]
  }
}

Response 200:
{
  "analysis_id": "task_analysis_892f3e1a",
  "task_classification": {
    "type": "migration",
    "complexity": "high",
    "risk_level": "medium-high",
    "estimated_duration_hours": 200,
    "confidence_score": 0.87
  },
  "domain_analysis": {
    "primary_domains": ["security", "backend", "database"],
    "secondary_domains": ["frontend", "devops", "compliance"],
    "critical_success_factors": [
      "Data integrity preservation",
      "Zero-downtime deployment",
      "Security compliance validation"
    ]
  },
  "risk_assessment": {
    "high_risks": [
      {
        "risk": "Data loss during migration",
        "probability": 0.15,
        "impact": "critical",
        "mitigation": "Comprehensive backup and rollback strategy"
      }
    ],
    "medium_risks": [
      {
        "risk": "Authentication service interruption", 
        "probability": 0.3,
        "impact": "high",
        "mitigation": "Blue-green deployment with fallback"
      }
    ]
  },
  "recommended_approach": {
    "strategy": "Phased migration with parallel systems",
    "phases": [
      {
        "name": "Preparation",
        "duration_hours": 40,
        "activities": ["Data audit", "OAuth2 design", "Testing framework"]
      },
      {
        "name": "Implementation", 
        "duration_hours": 80,
        "activities": ["OAuth2 service", "Migration scripts", "Frontend updates"]
      },
      {
        "name": "Migration",
        "duration_hours": 60,
        "activities": ["User migration", "System cutover", "Validation"]
      },
      {
        "name": "Cleanup",
        "duration_hours": 20,
        "activities": ["Legacy system removal", "Documentation", "Post-migration audit"]
      }
    ]
  }
}

Team Formation Integration

Create Team from Task Analysis

POST /api/v1/tasks/{analysis_id}/create-team
Authorization: Bearer {token}
Content-Type: application/json

{
  "team_configuration": {
    "formation_speed": "optimal", // immediate | fast | optimal | thorough
    "team_size_preference": "medium", // small | medium | large
    "experience_level": "senior", // junior | mixed | senior | expert
    "risk_tolerance": "low" // low | medium | high
  },
  "override_roles": {
    "add_required": ["compliance_specialist", "data_migration_expert"],
    "make_optional": ["frontend_developer"]
  },
  "constraints": {
    "exclude_agents": ["agent_junior_001"],
    "require_agents": ["agent_migration_expert"],
    "max_budget": 5000,
    "deadline": "2025-09-20T00:00:00Z"
  }
}

Response 201:
{
  "team_id": "team_auth_migration_v2",
  "formation_status": "in_progress",
  "estimated_formation_time": "45 minutes",
  "team_composition": {
    "total_roles": 7,
    "required_roles": 5,
    "optional_roles": 2,
    "recruiting_status": {
      "security_architect": "confirmed",
      "migration_specialist": "confirmed", 
      "backend_developer": "pending",
      "database_engineer": "recruiting",
      "compliance_specialist": "recruiting",
      "devops_engineer": "waitlisted",
      "qa_engineer": "optional_pending"
    }
  },
  "progress_tracking": {
    "gitea_issue_created": true,
    "issue_url": "https://gitea.chorus.services/legacy/user-system/issues/78",
    "p2p_channel_reserved": true,
    "channel_address": "ucxl://legacy:auth-migration@team_auth_migration_v2/#/"
  }
}

💬 Communication & Collaboration API

P2P Channel Management

Create Team Communication Channel

POST /api/v1/communication/channels
Authorization: Bearer {token}
Content-Type: application/json

{
  "team_id": "team_auth_sys_001",
  "channel_config": {
    "name": "auth-system-dev-team",
    "description": "OAuth2 Authentication System Development",
    "privacy": "team_only", // public | team_only | private
    "features": {
      "hmmm_reasoning": true,
      "file_sharing": true,
      "screen_sharing": false,
      "voice_channels": false,
      "code_collaboration": true
    }
  },
  "topic_streams": [
    {"name": "planning", "description": "Initial design discussions"},
    {"name": "implementation", "description": "Development coordination"},
    {"name": "review", "description": "Code and design reviews"},
    {"name": "testing", "description": "QA coordination"},
    {"name": "integration", "description": "Final assembly and deployment"}
  ],
  "moderation": {
    "auto_moderation": true,
    "require_approval": false,
    "archive_after_days": 90
  }
}

Response 201:
{
  "channel_id": "chan_auth_dev_7f3a2b1c",
  "ucxl_address": "ucxl://auth-system:implementation@team_auth_sys_001/#/",
  "p2p_network_id": "auth-system-dev-team",
  "created_at": "2025-09-03T15:45:00Z",
  "topic_streams": [
    {
      "stream_id": "planning_001",
      "ucxl_address": "ucxl://auth-system:implementation@team_auth_sys_001/#planning/",
      "subscribers": 0
    }
  ],
  "access_credentials": {
    "team_members": "automatic",
    "invitation_code": "invite_7f3a2b1c_temp",
    "expires_at": "2025-09-03T23:45:00Z"
  }
}

HMMM Reasoning Integration

Submit Reasoning Chain

POST /api/v1/communication/reasoning
Authorization: Bearer {agent_token}
Content-Type: application/json

{
  "channel_id": "chan_auth_dev_7f3a2b1c",
  "topic_stream": "implementation",
  "reasoning": {
    "agent_id": "agent_security_gamma",
    "context": "Evaluating JWT token storage strategies",
    "thinking_process": {
      "problem": "Need secure JWT storage that balances security and UX",
      "options_considered": [
        {
          "option": "HttpOnly cookies",
          "pros": ["XSS protection", "Automatic handling"],
          "cons": ["CSRF vulnerability", "SPA complexity"]
        },
        {
          "option": "Local storage",
          "pros": ["Simple implementation", "SPA friendly"],
          "cons": ["XSS vulnerability", "No automatic expiry"]
        },
        {
          "option": "Memory + refresh pattern",
          "pros": ["Maximum security", "Automatic cleanup"],
          "cons": ["Implementation complexity", "User experience impact"]
        }
      ],
      "analysis": "Given our high security requirements and SPA architecture, recommend memory + refresh pattern with secure HttpOnly refresh tokens",
      "confidence": 0.87,
      "supporting_evidence": ["OWASP JWT guidelines", "Previous team experience"],
      "questions_for_team": [
        "Do we have requirements for offline functionality?",
        "What's our tolerance for login frequency?"
      ]
    }
  },
  "requesting_feedback": true,
  "decision_required": true,
  "related_artifacts": ["jwt_architecture_doc", "security_requirements"]
}

Response 201:
{
  "reasoning_id": "reason_jwt_storage_001",
  "published_at": "2025-09-05T10:30:00Z",
  "ucxl_address": "ucxl://auth-system:implementation@team_auth_sys_001/#implementation/reason_jwt_storage_001",
  "broadcast_status": "sent_to_all_members",
  "team_notification": "sent",
  "slurp_ingestion": "queued",
  "feedback_thread": {
    "thread_id": "feedback_jwt_001",
    "participants_needed": ["backend_developer", "frontend_developer"],
    "deadline": "2025-09-05T18:00:00Z"
  }
}

Consensus & Decision Making

Initiate Team Vote

POST /api/v1/teams/{team_id}/votes
Authorization: Bearer {agent_token}
Content-Type: application/json

{
  "vote_title": "JWT Storage Strategy Decision",
  "description": "Choose the JWT token storage strategy for the OAuth2 implementation",
  "type": "single_choice", // single_choice | multiple_choice | approval | ranking
  "consensus_threshold": "majority", // simple | majority | supermajority | unanimous
  "options": [
    {
      "id": "option_httponly_cookies",
      "title": "HttpOnly Cookies",
      "description": "Store tokens in HttpOnly cookies with CSRF protection"
    },
    {
      "id": "option_memory_refresh",
      "title": "Memory + Refresh Pattern", 
      "description": "Keep access tokens in memory with secure refresh tokens"
    },
    {
      "id": "option_hybrid",
      "title": "Hybrid Approach",
      "description": "Use memory for access tokens, HttpOnly for refresh tokens"
    }
  ],
  "voting_period": {
    "duration_hours": 8,
    "deadline": "2025-09-05T18:30:00Z"
  },
  "eligibility": {
    "roles": ["security_architect", "backend_developer", "frontend_developer"],
    "minimum_participation": 3
  },
  "context": {
    "reasoning_references": ["reason_jwt_storage_001"],
    "decision_impact": "critical",
    "implementation_dependencies": ["api_design", "frontend_auth_flow"]
  }
}

Response 201:
{
  "vote_id": "vote_jwt_strategy_001",
  "status": "active",
  "created_at": "2025-09-05T10:30:00Z",
  "voting_ends_at": "2025-09-05T18:30:00Z",
  "eligible_voters": [
    {
      "agent_id": "agent_security_gamma",
      "role": "security_architect", 
      "voting_weight": 1.2
    },
    {
      "agent_id": "agent_backend_beta",
      "role": "backend_developer",
      "voting_weight": 1.0
    }
  ],
  "current_participation": {
    "votes_cast": 0,
    "participation_rate": 0.0,
    "quorum_reached": false
  },
  "notification_sent": true
}

🎯 SLURP Integration API

Artifact Management

Package Team Artifacts

POST /api/v1/teams/{team_id}/artifacts/package
Authorization: Bearer {token}
Content-Type: application/json

{
  "packaging_config": {
    "include_reasoning": true,
    "include_decisions": true,
    "include_code": true,
    "include_tests": true,
    "include_documentation": true,
    "include_metrics": true
  },
  "artifact_metadata": {
    "title": "OAuth2 Authentication System",
    "description": "Complete OAuth2 implementation with security best practices",
    "version": "1.0.0",
    "authors": ["team_auth_sys_001"],
    "license": "MIT",
    "tags": ["authentication", "oauth2", "security", "api"]
  },
  "quality_verification": {
    "run_tests": true,
    "security_scan": true,
    "performance_benchmark": true,
    "documentation_check": true
  },
  "slurp_settings": {
    "visibility": "public", // private | team | organization | public
    "indexing": "full", // minimal | standard | full
    "preservation_level": "permanent" // temporary | standard | permanent
  }
}

Response 202:
{
  "packaging_job_id": "pkg_auth_sys_001_v1",
  "status": "processing",
  "started_at": "2025-09-08T14:20:00Z",
  "estimated_completion": "2025-09-08T14:35:00Z",
  "progress": {
    "current_step": "collecting_artifacts",
    "steps_completed": 1,
    "total_steps": 8,
    "completion_percentage": 12.5
  },
  "preview_ucxl": "ucxl://teams:oauth2-auth@team_auth_sys_001/v1.0.0/#/",
  "tracking_url": "/api/v1/packaging/{packaging_job_id}/status"
}

Submit to SLURP

POST /api/v1/slurp/submit
Authorization: Bearer {token}
Content-Type: application/json

{
  "team_id": "team_auth_sys_001",
  "packaging_job_id": "pkg_auth_sys_001_v1",
  "submission_metadata": {
    "submission_type": "team_deliverable",
    "completion_status": "completed",
    "quality_gates_passed": [
      "security_review",
      "code_review", 
      "testing",
      "documentation",
      "consensus_approval"
    ],
    "team_consensus": {
      "vote_id": "vote_completion_001",
      "result": "unanimous_approval",
      "confidence_score": 0.94
    }
  },
  "institutional_compliance": {
    "provenance_verified": true,
    "secrets_clean": true,
    "temporal_pin": "2025-09-08T14:30:00Z",
    "decision_rationale": "Complete OAuth2 system with comprehensive security measures and team consensus approval"
  }
}

Response 201:
{
  "submission_id": "slurp_sub_001_v1",
  "slurp_address": "ucxl://teams:oauth2-auth@team_auth_sys_001/v1.0.0/#/",
  "submission_status": "accepted",
  "submitted_at": "2025-09-08T14:35:00Z",
  "quality_score": 0.91,
  "institutional_score": 0.96,
  "artifacts": {
    "total_files": 45,
    "code_files": 23,
    "test_files": 12,
    "documentation": 8,
    "reasoning_chains": 34,
    "decisions": 7
  },
  "slurp_metadata": {
    "indexed": true,
    "searchable": true,
    "citable": true,
    "preservation_status": "permanent"
  }
}

🔍 Analytics & Reporting API

Team Performance Analytics

Get Team Performance Metrics

GET /api/v1/analytics/teams/{team_id}/performance
Authorization: Bearer {token}
Query Parameters:
  - period: day | week | month | custom
  - start_date: 2025-09-01T00:00:00Z
  - end_date: 2025-09-08T23:59:59Z
  - metrics: completion_time,quality_score,consensus_rate

Response 200:
{
  "team_id": "team_auth_sys_001",
  "analysis_period": {
    "start": "2025-09-03T12:30:00Z",
    "end": "2025-09-08T14:35:00Z",
    "duration_hours": 122.08
  },
  "performance_metrics": {
    "completion_time": {
      "actual_hours": 122.08,
      "estimated_hours": 120,
      "efficiency_score": 0.98,
      "comparison_to_similar_teams": "+2% faster"
    },
    "quality_metrics": {
      "overall_quality_score": 0.91,
      "code_quality": 0.89,
      "test_coverage": 0.87,
      "security_score": 0.95,
      "documentation_completeness": 0.88
    },
    "collaboration_effectiveness": {
      "consensus_rate": 0.95,
      "decision_speed_avg_hours": 4.2,
      "communication_frequency": 0.85,
      "conflict_resolution_time_avg_hours": 1.8,
      "peer_rating_average": 4.6
    },
    "productivity_indicators": {
      "commits_per_day": 22.3,
      "artifacts_created": 45,
      "reasoning_chains": 34,
      "decisions_made": 7,
      "milestones_achieved": 4
    }
  },
  "team_dynamics": {
    "most_active_agent": "agent_security_gamma",
    "leadership_rotation": true,
    "knowledge_sharing_score": 0.88,
    "innovation_index": 0.76
  },
  "success_predictors": {
    "completion_probability": 0.94,
    "quality_forecast": 0.89,
    "stakeholder_satisfaction_prediction": 0.87
  }
}

System-Wide Analytics

Get Platform Overview

GET /api/v1/analytics/platform/overview
Authorization: Bearer {token}

Response 200:
{
  "timestamp": "2025-09-08T15:00:00Z",
  "system_status": "operational",
  "global_metrics": {
    "active_teams": 23,
    "total_agents": 47,
    "teams_formed_today": 3,
    "teams_completed_today": 1,
    "average_team_formation_time_minutes": 18.5,
    "platform_uptime": 0.999
  },
  "agent_network": {
    "online_agents": 44,
    "busy_agents": 31,
    "available_agents": 13,
    "average_load": 0.67,
    "network_health_score": 0.93
  },
  "team_formation_trends": {
    "success_rate_7d": 0.91,
    "average_team_size": 4.2,
    "most_requested_roles": ["backend_developer", "security_architect", "qa_engineer"],
    "formation_bottlenecks": ["security_architect", "ml_engineer"]
  },
  "quality_trends": {
    "average_completion_quality": 0.87,
    "consensus_achievement_rate": 0.92,
    "artifact_reuse_rate": 0.34,
    "continuous_improvement_score": 0.78
  },
  "resource_utilization": {
    "compute_utilization": 0.68,
    "storage_usage_gb": 847.3,
    "network_bandwidth_utilization": 0.45,
    "cost_efficiency_score": 0.82
  }
}

📡 WebSocket Events

Real-time Event Streaming

WebSocket Connection & Subscription

// Connection
const ws = new WebSocket('wss://whoosh.chorus.services/ws');

// Authentication
ws.send(JSON.stringify({
  type: 'authenticate',
  token: 'bearer_jwt_token_here'
}));

// Subscribe to team events
ws.send(JSON.stringify({
  type: 'subscribe',
  topics: [
    'team.team_auth_sys_001',
    'agent.agent_security_gamma',
    'platform.alerts'
  ]
}));

Event Types & Payloads

Team Formation Events:

{
  "type": "team.formation_started",
  "team_id": "team_auth_sys_001", 
  "timestamp": "2025-09-03T12:30:00Z",
  "data": {
    "team_name": "Auth System Implementation Team",
    "roles_needed": 5,
    "estimated_formation_time_minutes": 15
  }
}

{
  "type": "team.agent_joined",
  "team_id": "team_auth_sys_001",
  "timestamp": "2025-09-03T13:15:00Z",
  "data": {
    "agent_id": "agent_security_gamma",
    "role": "security_architect",
    "team_size": 3,
    "roles_remaining": 2
  }
}

Agent Activity Events:

{
  "type": "agent.status_changed",
  "agent_id": "agent_security_gamma",
  "timestamp": "2025-09-05T09:10:00Z",
  "data": {
    "previous_status": "idle",
    "current_status": "active",
    "current_load": 0.65,
    "team_assignments": ["team_auth_sys_001"]
  }
}

{
  "type": "agent.reasoning_shared",
  "agent_id": "agent_security_gamma",
  "timestamp": "2025-09-05T10:30:00Z", 
  "data": {
    "reasoning_id": "reason_jwt_storage_001",
    "team_id": "team_auth_sys_001",
    "topic": "JWT Storage Strategy",
    "feedback_requested": true
  }
}

Consensus & Decision Events:

{
  "type": "team.vote_started",
  "team_id": "team_auth_sys_001",
  "timestamp": "2025-09-05T10:30:00Z",
  "data": {
    "vote_id": "vote_jwt_strategy_001",
    "title": "JWT Storage Strategy Decision",
    "eligible_voters": 4,
    "deadline": "2025-09-05T18:30:00Z"
  }
}

{
  "type": "team.consensus_reached",
  "team_id": "team_auth_sys_001",
  "timestamp": "2025-09-05T16:15:00Z",
  "data": {
    "vote_id": "vote_jwt_strategy_001",
    "winning_option": "option_memory_refresh",
    "consensus_type": "supermajority",
    "participation_rate": 1.0
  }
}

This API specification provides the complete interface for WHOOSH's transformation into an Autonomous AI Development Teams platform, enabling sophisticated team orchestration, agent coordination, and collaborative development processes across the CHORUS ecosystem.