# hoody-api Subskill ## Overview (80 lines) ### Service Purpose **hoody-api** is the core platform API that manages containers, projects, authentication, and infrastructure for the Hoody ecosystem. It serves as the central control plane for all platform operations, providing a comprehensive RESTful API accessible via the `hoody` CLI tool. ### When to Use This Service Use hoody-api for: - **User Management**: Account creation, authentication, profile updates - **Project Organization**: Creating and managing logical resource groupings - **Container Lifecycle**: Provisioning, configuration, monitoring, and lifecycle management - **Access Control**: Managing authentication tokens, permissions, and two-factor authentication - **Financial Operations**: Wallet management, billing, and payment processing - **Infrastructure**: Server rentals, storage shares, network configuration - **Monitoring**: Activity logs, events, notifications, and analytics ### Authentication Model All hoody-api operations require authentication through one of these methods: 1. **JWT Tokens**: Obtained via `hoody auth login` (expires in 1 day, refresh in 7 days) 2. **Long-term Auth Tokens**: Created via `hoody auth create` with optional IP restrictions 3. **Basic Authentication**: Username/password in development contexts **Key Authentication Commands**: ``` # Login with credentials hoody auth login # Use stored token hoody --token # Environment variable export HOODY_TOKEN= hoody ``` ### Service Philosophy & Integration hoody-api embodies Hoody's core principles: - **Zero-Configuration Infrastructure**: Automatic DNS, SSL, and routing - **Multi-Tenant Security**: Isolated environments per project/container - **API-First Design**: All operations available via CLI or REST API - **Consistent Patterns**: Uniform resource management across services **Relationship to Other Services**: - **Hoody Proxy**: Automatic routing uses container URLs following `{projectId}-{containerId}-{serviceId}.{node}.containers.hoody.com` - **CLI Integration**: All operations accessible via `hoody ` syntax - **Never Direct API Calls**: Always use `hoody` CLI commands, never raw HTTP/curl ### Output Conventions - Use `-o json` for machine-readable output in automation - Default output is human-readable table format - Always authenticate before operations - Always specify container context when needed with `-c ` --- ## Core Resource Workflows (500-700 lines) ### 1. Authentication & Account Management #### 1.1 User Authentication ``` # Login with username/password hoody auth login # Login with token (non-interactive) hoody auth login --token # Check current authentication status hoody auth current # Logout and invalidate tokens hoody auth logout ``` **Response Handling**: ``` { "status": "authenticated", "user": { "id": "user_abc123", "username": "developer", "email": "dev@example.com" }, "token": { "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...", "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4..." } } ``` #### 1.2 Account Operations ``` # Create new account hoody auth signup # Verify email with token from email hoody auth verify --token # Resend verification email hoody auth resend # Request password reset hoody auth forgot # Reset password with token hoody auth reset --token --new-password # Get available server regions hoody auth regions ``` #### 1.3 Two-Factor Authentication ``` # Setup 2FA (returns QR code and backup codes) hoody auth setup # Verify 2FA during login (after initial login returns temp_token) hoody auth verify --code <6-digit-otp-or-backup-code> # Check 2FA status hoody auth status # Disable 2FA (requires password and OTP) hoody auth disable --password --code # Regenerate backup codes hoody auth regenerate --password --code # Set OTP requirement for token operations hoody auth gate --enabled true ``` ### 2. Auth Token Management #### 2.1 Token Operations ``` # Create new auth token with optional restrictions hoody auth create # List all auth tokens hoody auth list # Get specific token details hoody auth get # Copy existing token configuration hoody auth copy # Update token properties hoody auth update # Delete token hoody auth delete ``` #### 2.2 Token Scoping ``` # Add realm restriction to token hoody auth add --realm-id # Remove realm restriction hoody auth remove --realm-id # Get current token metadata hoody auth get-current # Update current token's public profile hoody auth update ``` ### 3. Project Management #### 3.1 Basic Project Operations ``` # List all projects hoody projects list # Create new project hoody projects create --alias "My Project" --color "#ff6b6b" # Get project details hoody projects get # Update project hoody projects update --alias "Updated Name" # Delete project (requires confirmation) hoody projects delete --yes ``` **Project Creation Response**: ``` { "data": { "id": "proj_abc123def456", "alias": "My Project", "color": "#ff6b6b", "owner_id": "user_abc123", "created_at": "2024-01-15T10:30:00Z", "quotas": { "containers": 10, "storage_gb": 50 } } } ``` #### 3.2 Project Permissions ``` # List project permissions hoody projects list permissions # Grant access to another user hoody projects create permissions --user-id --level edit # Update permission level hoody projects update permissions --level read # Revoke access hoody projects delete permissions --yes ``` #### 3.3 Project Statistics ``` # Get aggregated stats for all containers in project hoody projects stats ``` ### 4. Container Lifecycle Management #### 4.1 Container CRUD Operations ``` # List containers in project hoody containers list # Create container in project hoody containers create --project --image # List all containers across projects hoody containers list # Get container details hoody containers get # Update container hoody containers update --alias "My Container" # Delete container hoody containers delete --yes # Get container status logs hoody containers status-logs ``` **Container Creation Example**: ``` hoody containers create \ --project proj_abc123def456 \ --image img_ubuntu2204 \ --alias "web-server" \ --env "PORT=8080,NODE_ENV=production" ``` #### 4.2 Container Operations ``` # Start container hoody containers manage start # Stop container hoody containers manage stop # Restart container hoody containers manage restart # Force stop container hoody containers manage force-stop # Pause container hoody containers manage pause # Resume container hoody containers manage resume ``` #### 4.3 Container Environment Variables ``` # List environment variables hoody containers list env # Set single environment variable hoody containers set --key API_KEY --value "secret123" # Bulk set environment variables hoody containers bulk-set --env "KEY1=value1,KEY2=value2" # Delete environment variable hoody containers delete env --yes ``` #### 4.4 Container Networking ``` # Get network configuration hoody network get -c # Update network proxy settings hoody network update -c --proxy-enabled true # Start network service hoody network start -c # Stop network service hoody network stop -c --yes # Delete network configuration hoody network delete -c --yes ``` #### 4.5 Container Firewall ``` # List all firewall rules hoody firewall list -c # Add ingress rule (allow SSH) hoody firewall create -c ingress \ --port 22 --protocol tcp --action allow --source 192.168.1.0/24 # Add egress rule (block outbound to certain IPs) hoody firewall create -c egress \ --port 443 --protocol tcp --action deny --destination "10.0.0.0/8" # Toggle rule state (disable without deleting) hoody firewall toggle -c ingress --rule-id --state disabled # Reset firewall to default (open) hoody firewall reset -c --yes ``` #### 4.6 Container Snapshots ``` # List snapshots hoody snapshots list -c # Create snapshot hoody snapshots create -c --name "pre-update-backup" # Restore from snapshot hoody snapshots restore -c --snapshot-name "pre-update-backup" --yes # Update snapshot alias hoody snapshots update-alias -c --snapshot-name "old-snap" --alias "production-backup" # Delete snapshot hoody snapshots delete -c --snapshot-name "old-snap" --yes ``` #### 4.7 Container Statistics & Monitoring ``` # Get real-time resource usage hoody containers stats # Get container authorization claim hoody containers authorize ``` ### 5. Proxy Configuration #### 5.1 Proxy Aliases ``` # Create custom domain alias hoody proxy create --container --alias "myapp.example.com" # List all proxy aliases hoody proxy list # Get alias details hoody proxy get # Update alias hoody proxy update --alias "new-domain.com" # Enable/disable alias hoody proxy set-state --enabled false # Delete alias hoody proxy delete --yes ``` #### 5.2 Container Proxy Settings ``` # Get proxy root settings hoody containers get proxy # Update proxy settings hoody containers update proxy --enable-proxy true # List proxy groups hoody containers list proxy groups # List services in proxy config hoody containers list proxy services # Get merged proxy view for service hoody containers get proxy ``` #### 5.3 Proxy Hooks ``` # List all hooks for container hoody containers list hooks # List hooks for specific service hoody containers list-service # Create new hook hoody containers create hooks \ --match "path:/api/*" \ --script "javascript:function(request) { return request; }" \ --timeout 5000 # Update hook hoody containers update hooks \ --match "path:/v2/*" # Move hook to new position hoody containers move hooks --position 0 # Delete hook hoody containers delete hooks --yes # Clear all hooks for service hoody containers clear-service ``` #### 5.4 Proxy Permissions ``` # Get container proxy permissions hoody containers get proxy permissions # Replace entire permissions JSON hoody containers replace proxy permissions --json-file permissions.json # Update default policy hoody containers default proxy permissions --policy deny # Enable/disable proxy hoody containers state proxy permissions --enabled true # Set JWT authentication group hoody containers set proxy permissions jwt \ --group-name "admin" --issuer "https://auth.example.com" --audience "myapp" # Set password authentication group hoody containers set proxy permissions password \ --group-name "basic" --username "admin" --password-hash "$2a$10$..." # Set IP authentication group hoody containers set proxy permissions ip \ --group-name "office" --allowed-ips "192.168.1.0/24,10.0.0.0/8" # Set token authentication group hoody containers set proxy permissions token \ --group-name "api" --token-header "X-API-Key" --token-value "secret123" # Set program permissions for group hoody containers set proxy permissions program \ --group-name "admin" --program "/api/admin/*" --permission allow # Clear program permissions hoody containers clear proxy permissions program --group-name "admin" # Delete specific program permission hoody containers delete proxy permissions program \ --group-name "admin" --program "/api/admin/*" --yes ``` ### 6. User & Account Management #### 6.1 User Operations ``` # Get user profile by ID hoody users get # Update user profile hoody users update --alias "New Display Name" # Retry free-tier setup hoody users retry-setup ``` #### 6.2 Activity Monitoring ``` # Get activity logs hoody activity logs --start 2024-01-01 --end 2024-01-31 # Get activity statistics hoody activity stats ``` ### 7. Server & Rental Management #### 7.1 Server Marketplace ``` # Browse available servers hoody servers marketplace # Rent a server hoody servers rent --days 30 --yes # List your rentals hoody servers list-rentals # Get rental details hoody servers get-rental # Extend rental hoody servers extend --days 7 --yes # Execute command on server hoody servers exec --command "restart-services" # Get available commands hoody servers commands ``` ### 8. Storage Shares #### 8.1 Share Management ``` # Create storage share hoody storage create \ --source-container \ --target-container \ --path "/data/shared" \ --mount-point "/mnt/shared" # List shares you've created hoody storage list # Get share details hoody storage get # Update share properties hoody storage update --mode read-write --metadata '{"purpose": "backups"}' # Delete share hoody storage delete --yes # List incoming shares (shares targeting your containers) hoody storage list --incoming # Toggle mount for incoming share hoody storage toggle-mount --share-id --enabled true ``` ### 9. Wallet & Billing #### 9.1 Balance Management ``` # Get all balances (general + AI) hoody wallet get # Get general balance only hoody wallet general # Get AI credit balance hoody wallet ai # Transfer from general to AI balance hoody wallet transfer --amount 50.00 --yes ``` #### 9.2 Transactions & Invoices ``` # List transactions hoody wallet list # Get transaction details hoody wallet get # List invoices hoody wallet list invoices # Get invoice details hoody wallet get invoices # Download invoice PDF hoody wallet download # Generate invoice for transaction hoody wallet generate ``` #### 9.3 Payment Methods ``` # List payment methods hoody wallet list methods # Add payment method hoody wallet create methods --type credit_card --number "4242424242424242" --exp-month 12 --exp-year 2025 # Update payment method hoody wallet update methods --exp-month 11 # Delete payment method hoody wallet delete methods --yes # Set default payment method hoody wallet set-default ``` #### 9.4 Payments & Checkout ``` # Process payment hoody wallet create payment --method-id --amount 25.00 --currency USD --yes # Get payment status hoody wallet status # Create Stripe checkout session hoody wallet create checkout --amount 100.00 # List Stripe payment intents hoody wallet list intents # Get specific payment intent hoody wallet get intents ``` ### 10. Container Images Marketplace #### 10.1 Image Browsing ``` # List public images hoody images list # Get image details hoody images get # Get image icon hoody images icon # List images you own hoody images mine ``` #### 10.2 Image Acquisition ``` # Import free image hoody images import-free # Purchase paid image hoody images purchase --yes # Rate an image hoody images rate --rating 4 ``` ### 11. Pool Management (Team Collaboration) #### 11.1 Pool Operations ``` # List pools you belong to hoody pools list # Create new pool hoody pools create --name "Dev Team" --description "Development team collaboration" # Get pool details hoody pools get # Update pool hoody pools update --name "Production Team" # Delete pool hoody pools delete --yes # List pending invitations hoody pools list invitations # Accept invitation hoody pools accept # Reject invitation hoody pools reject ``` #### 11.2 Pool Member Management ``` # Invite member to pool hoody pools invite --user-id --role member # Update member role hoody pools update-role --role admin # Remove member hoody pools delete --yes ``` ### 12. Notifications & Events #### 12.1 Notifications ``` # List public notifications (no auth required) hoody inbox list-public # List your notifications hoody inbox list # Mark notification as read hoody inbox mark # Mark all notifications as read hoody inbox mark-all ``` #### 12.2 Events & Activity ``` # Get event statistics hoody events stats # List events with filters hoody events list --type container.created --start 2024-01-01 # Get event details hoody events get # Delete single event hoody events delete --yes # Bulk delete events hoody events bulk-delete --type container.deleted --before 2023-12-31 --yes # Cleanup old events hoody events cleanup --days 30 --yes ``` ### 13. AI Models ``` # List available AI models hoody ai list ``` ### 14. System Utilities ``` # Get your public IP information hoody ip get # List your realm IDs hoody realms list # Get Hoody API signing public key hoody meta get # Get public key for verification hoody meta get --purpose signing ``` ### 15. Encrypted Vault ``` # Get vault statistics hoody vault stats # List vault keys hoody vault list # Get vault key value hoody vault get # Set vault key value hoody vault set --value '{"api_key": "sk_live_abc123"}' # Delete vault key hoody vault delete --yes # Clear entire vault (dangerous!) hoody vault clear --yes ``` --- ## Advanced Operations (200-300 lines) ### 1. Full Container Lifecycle Workflow ``` # 1. Create project hoody projects create --alias "Production App" --color "#4CAF50" # 2. Create container with initial configuration hoody containers create \ --project \ --image img_ubuntu2204 \ --alias "web-api" \ --env "NODE_ENV=production,PORT=8080" \ -o json # 3. Configure network (proxy enabled) hoody network update -c --proxy-enabled true # 4. Set firewall rules hoody firewall create -c ingress \ --port 8080 --protocol tcp --action allow --source "0.0.0.0/0" hoody firewall create -c egress \ --port 443 --protocol tcp --action allow \ --destination "api.stripe.com,api.github.com" # 5. Configure proxy authentication hoody containers set proxy permissions jwt \ --group-name "authenticated" \ --issuer "https://auth.mycompany.com" \ --audience "my-api" hoody containers default proxy permissions --policy deny # 6. Create backup snapshot hoody snapshots create -c --name "initial-deploy" # 7. Set up monitoring hoody containers stats ``` ### 2. Multi-Container Microservices Setup ``` # Create shared network between containers hoody storage create \ --source-container \ --target-container \ --path "/data/shared" \ --mount-point "/mnt/shared" # Configure inter-container communication hoody firewall create -c ingress \ --port 8081 --protocol tcp --action allow \ --source # Set up shared environment secrets hoody vault set shared-db-url \ --value "postgres://user:pass@db.internal:5432/prod" hoody containers bulk-set \ --env "DB_URL=\${vault:shared-db-url}" hoody containers bulk-set \ --env "DB_URL=\${vault:shared-db-url}" ``` ### 3. Batch Operations & Automation ``` # Bulk container restart (project-wide) for container_id in $(hoody containers list -o json | jq -r '.[].id'); do hoody containers manage $container_id restart done # Bulk environment variable update hoody containers list -o json | \ jq -r '.[].id' | \ xargs -I {} hoody containers set {} --key "NEW_FEATURE_FLAG" --value "true" # Export container configurations hoody containers list -o json > containers-backup.json # Import environment variables from file hoody containers bulk-set --env "$(cat .env.production)" ``` ### 4. Error Recovery Patterns #### Container Recovery from Failed State ``` # 1. Check container status hoody containers get # 2. If stuck, force stop and restart hoody containers manage force-stop hoody containers manage start # 3. If configuration corrupted, restore from snapshot hoody snapshots list -c hoody snapshots restore -c --snapshot-name "last-good" --yes # 4. If network issues, reset network config hoody network delete -c --yes hoody network update -c --proxy-enabled true ``` #### Permission Reset Workflow ``` # 1. Export current permissions hoody containers get proxy permissions -o json > perms-backup.json # 2. Reset to open access temporarily hoody containers delete proxy permissions --yes # 3. Reconfigure step by step hoody containers set proxy permissions password \ --group-name "emergency" --username "admin" --password-hash "$2a$10$..." hoody containers default proxy permissions --policy deny ``` ### 5. Complex Proxy Configuration ``` # 1. Set up JWT authentication for API routes hoody containers set proxy permissions jwt \ --group-name "api-auth" \ --issuer "https://accounts.google.com" \ --audience "my-webapp-client-id" # 2. Set up IP whitelist for internal services hoody containers set proxy permissions ip \ --group-name "internal" \ --allowed-ips "10.0.0.0/8,172.16.0.0/12" # 3. Set program permissions hoody containers set proxy permissions program \ --group-name "api-auth" --program "/api/v1/*" --permission allow hoody containers set proxy permissions program \ --group-name "internal" --program "/internal/*" --permission allow hoody containers set proxy permissions program \ --group-name "public" --program "/health" --permission allow # 4. Configure request hooks for logging hoody containers create hooks "web-service" \ --match "path:*" \ --script 'javascript:function(req) { console.log(`${req.method} ${req.path}`); return req; }' \ --timeout 1000 # 5. Enable proxy with deny default hoody containers state proxy permissions --enabled true hoody containers default proxy permissions --policy deny ``` ### 6. Complete Server Rental & Deployment ``` # 1. Browse available servers hoody servers marketplace --region us-east-1 --type gpu # 2. Rent server for 30 days hoody servers rent --days 30 --yes # 3. Deploy application to rented server hoody containers create \ --server \ --image img_python39 \ --alias "ml-training" \ --env "GPU_ENABLED=true,CUDA_VERSION=11.8" # 4. Configure firewall for SSH access hoody firewall create -c ingress \ --port 22 --protocol tcp --action allow --source "your-ip/32" # 5. Monitor resource usage hoody containers stats # 6. Extend rental if needed hoody servers extend --days 7 --yes ``` ### 7. Team Collaboration with Pools ``` # 1. Create team pool hoody pools create --name "Frontend Team" --description "React development team" # 2. Invite team members hoody pools invite --user-id --role developer hoody pools invite --user-id --role admin # 3. Create shared project within pool context hoody projects create --alias "Shared Components" --pool # 4. Set up shared vault for team secrets hoody vault set team-api-key --value "sk_team_abc123" hoody vault set team-db-url --value "postgres://team:pass@db.example.com/teamdb" # 5. Create containers with shared access hoody containers create \ --project \ --image img_node18 \ --alias "component-library" \ --shared-vault team-api-key,team-db-url ``` ### 8. Disaster Recovery & Backup ``` # 1. Full project backup PROJECT_ID="proj_abc123" BACKUP_DIR="backup_$(date +%Y%m%d)" mkdir -p $BACKUP_DIR # Export project configuration hoody projects get $PROJECT_ID -o json > $BACKUP_DIR/project.json # Export all container configurations hoody containers list $PROJECT_ID -o json > $BACKUP_DIR/containers.json # Export environment variables for container in $(jq -r '.[].id' $BACKUP_DIR/containers.json); do hoody containers list $container env -o json > $BACKUP_DIR/env_${container}.json done # Export firewall rules for container in $(jq -r '.[].id' $BACKUP_DIR/containers.json); do hoody firewall list -c $container -o json > $BACKUP_DIR/firewall_${container}.json done # 2. Create snapshots for all containers for container in $(jq -r '.[].id' $BACKUP_DIR/containers.json); do hoody snapshots create -c $container --name "disaster-backup-$(date +%Y%m%d)" done ``` --- ## Quick Reference (100-150 lines) ### Endpoint Groups & CLI Commands | Resource Group | CLI Command | Base Endpoint Path | |----------------|------------|-------------------| | Authentication | `hoody auth` | `/api/v1/auth/` | | Auth Tokens | `hoody auth` | `/api/v1/auth/tokens/` | | Projects | `hoody projects` | `/api/v1/projects/` | | Containers | `hoody containers` | `/api/v1/containers/` | | Container Images | `hoody images` | `/api/v1/images/` | | Users | `hoody users` | `/api/v1/users/` | | Servers | `hoody servers` | `/api/v1/servers/` | | Rentals | `hoody servers` | `/api/v1/rentals/` | | Realms | `hoody realms` | `/api/v1/realms/` | | Vault | `hoody vault` | `/api/v1/vault/` | | Notifications | `hoody inbox` | `/api/v1/notifications/` | | Events | `hoody events` | `/api/v1/events/` | | Storage Shares | `hoody storage` | `/api/v1/storage/` | | Wallet | `hoody wallet` | `/api/v1/wallet/` | | Pools | `hoody pools` | `/api/v1/pools/` | | Proxy | `hoody proxy` | `/api/v1/proxy/` | | AI Models | `hoody ai` | `/api/v1/ai/` | | Meta | `hoody meta` | `/api/v1/meta/` | | IP | `hoody ip` | `/api/v1/ip/` | ### Essential Parameters **Common Flags**: - `-o json`: JSON output format - `-c `: Target specific container - `--yes`: Skip confirmation prompts - `--token `: Authentication token - `--filter "key=value"`: Filter results **Container Targeting**: ``` # Always specify container when needed hoody containers get -c hoody firewall list -c hoody snapshots list -c ``` ### Response Formats **Standard Success Response**: ``` { "data": { ... }, "meta": { "request_id": "req_abc123", "timestamp": "2024-01-15T10:30:00Z" } } ``` **List Response with Pagination**: ``` { "data": [ ... ], "meta": { "total": 42, "page": 1, "per_page": 20, "pages": 3 } } ``` **Error Response**: ``` { "error": { "code": "PERMISSION_DENIED", "message": "Insufficient permissions", "details": { "required": "containers.edit", "current": "containers.view" } } } ``` ### Common Workflows **Container Lifecycle**: ``` hoody containers create → hoody containers manage start → hoody containers stats → hoody containers manage stop → hoody containers delete ``` **Authentication Flow**: ``` hoody auth login → hoody auth current → hoody auth create (token) → hoody auth list ``` **Project Setup**: ``` hoody projects create → hoody containers create (in project) → hoody projects stats → hoody projects delete ``` **Backup & Restore**: ``` hoody snapshots create → hoody snapshots list → hoody snapshots restore ``` ### Important Notes 1. **Always authenticate first**: `hoody auth login` or provide `--token` 2. **Container context matters**: Use `-c` for container-specific operations 3. **Confirmation required**: Add `--yes` for destructive operations 4. **Check status between operations**: Use `hoody containers get` to verify state 5. **Use JSON for automation**: `-o json` enables machine processing 6. **Never use raw HTTP**: Always use `hoody` CLI commands 7. **Realms are 24-hex identifiers**: Used for token scoping and project organization