<!--
hoody-api Subskill (http)
Auto-generated by Hoody Skills Generator
Generated: 2026-06-20T00:44:21.973Z
Model: mimo-v2.5-pro
Mode: http


Tokens: 33564

DO NOT EDIT MANUALLY - Changes will be overwritten on next generation
-->

# hoody-api Subskill

## Service Overview

**hoody-api** is the core platform API for Hoody, serving as the central management layer for all infrastructure resources. It handles authentication, user management, project organization, container lifecycle, networking, proxy configuration, storage sharing, billing, server rentals, and more. Every other Hoody service depends on hoody-api for identity, authorization, and resource discovery.

### When to Use hoody-api

- **Authentication**: Login, signup, OAuth flows, token management, 2FA setup
- **Resource Management**: Create, update, delete, and monitor projects, containers, servers
- **Networking**: Configure container networks, firewalls, proxy rules, custom aliases
- **Billing**: Manage wallets, payment methods, invoices, server rentals
- **Collaboration**: Pool management, permission grants, storage sharing
- **Configuration**: Environment variables, snapshots, vault secrets
- **Discovery**: AI model catalogs, public images, public keys, social stats

### Authentication Model

All endpoints (except public ones) require authentication via one of:

1. **JWT Access Token** — obtained via `POST /api/v1/users/auth/login`, passed as `Authorization: Bearer {accessToken}`. Expires in 1 day.
2. **Auth Token** — long-lived API tokens created via `POST /api/v1/auth/tokens`, passed as `Authorization: Bearer {tokenValue}`.
3. **Refresh Token** — used exclusively with `POST /api/v1/users/auth/refresh` to obtain new access tokens. Expires in 7 days.

When 2FA is enabled, login returns a `temp_token` that must be verified via `POST /api/v1/users/auth/2fa/verify` before receiving the final access token.

### Proxy Routing System

All Hoody Kit services use automatic domain-based routing:

```
https://{projectId}-{containerId}-{serviceName}-{serviceId}.{node}.containers.hoody.com
```

This pattern provides zero-DNS configuration, automatic SSL/TLS termination, built-in authentication, and multi-tenant isolation. Custom aliases can mask these URLs via the Proxy Aliases endpoints.

### How It Fits Into Hoody Philosophy

hoody-api is the authoritative source of truth for all platform resources. It enforces RBAC, manages cryptographic identities (ED25519 keys), provides signed container authorization claims, and ensures isolation between projects, pools, and tenants. Every workflow on the Hoody platform starts and ends with hoody-api.

---

## Core Resource Workflows

### 1. Authentication

#### 1.1 Sign Up and Email Verification

Create a new account and verify the email address.

```
# Step 1: Sign up
curl -s -X POST "https://api.hoody.com/api/v1/auth/signup" \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"SecureP@ss123"}'
```

Expected response confirms account created and verification email sent.

```
# Step 2: Verify email (token from email link)
curl -s -X POST "https://api.hoody.com/api/v1/auth/verify-email" \
  -H "Content-Type: application/json" \
  -d '{"token":"verification_token_from_email"}'
```

Returns full login credentials on success.

```
# Resend verification if needed (always returns success to prevent enumeration)
curl -s -X POST "https://api.hoody.com/api/v1/auth/resend-verification" \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com"}'
```

#### 1.2 Login and Token Lifecycle

```
# Login with credentials
curl -s -X POST "https://api.hoody.com/api/v1/users/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"SecureP@ss123"}'
```

Returns `accessToken` (1-day expiry) and `refreshToken` (7-day expiry).

```
# Refresh access token before expiry
curl -s -X POST "https://api.hoody.com/api/v1/users/auth/refresh" \
  -H "Content-Type: application/json" \
  -d '{"refreshToken":"your_refresh_token_here"}'
```

Returns new access token and new refresh token (rotate both).

```
# Get current user profile
curl -s "https://api.hoody.com/api/v1/users/auth/me" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Logout (creates audit log entry; client should discard tokens)
curl -s -X POST "https://api.hoody.com/api/v1/users/auth/logout" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

#### 1.3 Password Reset

```
# Request password reset email
curl -s -X POST "https://api.hoody.com/api/v1/auth/forgot-password" \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com"}'
```

```
# Reset password using token from email
curl -s -X POST "https://api.hoody.com/api/v1/auth/reset-password" \
  -H "Content-Type: application/json" \
  -d '{"token":"reset_token_from_email","password":"NewSecureP@ss456"}'
```

#### 1.4 OAuth Flows (GitHub, Google)

These are browser-only flows initiated by redirecting the user:

```
# GitHub OAuth - redirect user to:
# https://api.hoody.com/api/v1/auth/github

# Google OAuth - redirect user to:
# https://api.hoody.com/api/v1/auth/google

# For popup-based flows, initiate a launch ticket:
curl -s -X POST "https://api.hoody.com/api/v1/auth/launch/initiate" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{}'
```

The response contains a `launch_url`. Redirect the popup to this URL, which consumes the ticket and runs the OAuth redirect flow.

```
# Cancel an intent (dismiss confirmation page)
curl -s -X POST "https://api.hoody.com/api/v1/auth/intent/cancel" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_INTENT_TOKEN" \
  -d '{}'
```

#### 1.5 Available Regions

```
# Public endpoint - no auth required
curl -s "https://api.hoody.com/api/v1/auth/available-regions"
```

Returns regions where free-tier servers exist with boolean availability flags.

---

### 2. Two-Factor Authentication (2FA)

#### 2.1 Enable 2FA

```
# Step 1: Begin setup (requires password)
curl -s -X POST "https://api.hoody.com/api/v1/users/auth/2fa/setup" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"password":"SecureP@ss123"}'
```

Returns QR code (for authenticator app) and backup codes. **Save backup codes immediately — they are shown only once.**

```
# Step 2: Verify setup with first OTP code
curl -s -X POST "https://api.hoody.com/api/v1/users/auth/2fa/verify-setup" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"code":"123456"}'
```

#### 2.2 Login with 2FA

When 2FA is enabled, login returns a `temp_token` instead of a full access token.

```
# Step 1: Login (returns temp_token)
curl -s -X POST "https://api.hoody.com/api/v1/users/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"SecureP@ss123"}'
```

```
# Step 2: Verify 2FA code (OTP or backup code)
curl -s -X POST "https://api.hoody.com/api/v1/users/auth/2fa/verify" \
  -H "Content-Type: application/json" \
  -d '{"code":"123456"}'
```

Use `temp_token` as the bearer token for this request. Returns final `accessToken` and `refreshToken`.

#### 2.3 Manage 2FA Status

```
# Check 2FA status
curl -s "https://api.hoody.com/api/v1/users/auth/2fa/status" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Regenerate backup codes (requires password + OTP)
curl -s -X POST "https://api.hoody.com/api/v1/users/auth/2fa/backup-codes/regenerate" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"password":"SecureP@ss123","code":"123456"}'
```

```
# Disable 2FA (requires password + OTP or backup code)
curl -s -X DELETE "https://api.hoody.com/api/v1/users/auth/2fa" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"password":"SecureP@ss123","code":"123456"}'
```

#### 2.4 Token Gate (OTP for Token Mutations)

```
# Enable OTP requirement for token mutations
curl -s -X PUT "https://api.hoody.com/api/v1/users/auth/2fa/token-gate" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"enabled":true}'
```

```
# Disable OTP requirement (requires password + OTP)
curl -s -X PATCH "https://api.hoody.com/api/v1/users/auth/2fa/token-gate" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"enabled":false}'
```

---

### 3. Auth Tokens

Long-lived API tokens for programmatic access, with optional IP restrictions, realm scoping, and expiration.

#### 3.1 List and Create Tokens

```
# List all tokens (token values not included)
curl -s "https://api.hoody.com/api/v1/auth/tokens" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Create a new token
curl -s -X POST "https://api.hoody.com/api/v1/auth/tokens" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"alias":"ci-deploy-token"}'
```

Returns the full token value on creation — store it securely.

#### 3.2 Manage Individual Tokens

```
# Get token details (value not included)
curl -s "https://api.hoody.com/api/v1/auth/tokens/TOKEN_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Update token (alias, IP restrictions, expiration, enabled status)
curl -s -X PATCH "https://api.hoody.com/api/v1/auth/tokens/TOKEN_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"alias":"renamed-token","enabled":true}'
```

```
# Copy token configuration to a new token
curl -s -X POST "https://api.hoody.com/api/v1/auth/tokens/TOKEN_ID/copy" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{}'
```

```
# Delete a token (immediately invalidates it)
curl -s -X DELETE "https://api.hoody.com/api/v1/auth/tokens/TOKEN_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

#### 3.3 Realm Scoping

```
# Add a realm to a token (idempotent)
curl -s -X POST "https://api.hoody.com/api/v1/auth/tokens/TOKEN_ID/add-realm" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"realm_id":"abcdef1234567890abcdef12"}'
```

```
# Remove a realm from a token (idempotent)
curl -s -X POST "https://api.hoody.com/api/v1/auth/tokens/TOKEN_ID/remove-realm" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"realm_id":"abcdef1234567890abcdef12"}'
```

#### 3.4 Current Token Info and Public Profiles

```
# Get current token metadata, permissions, realm restrictions
curl -s "https://api.hoody.com/api/v1/auth/tokens/me" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"
```

```
# Update current token's public profile
curl -s -X PUT "https://api.hoody.com/api/v1/auth/tokens/me/public-profile" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -d '{}'
```

```
# Resolve a public profile by ED25519 public key
curl -s "https://api.hoody.com/api/v1/auth/tokens/public-profiles/ED25519_PUBLIC_KEY_HEX" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

---

### 4. Users

#### 4.1 User Profiles

```
# Get your own profile
curl -s "https://api.hoody.com/api/v1/users/auth/me" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Get user by ID (admins can view any; regular users only themselves)
curl -s "https://api.hoody.com/api/v1/users/USER_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Update user profile (alias, password)
curl -s -X PATCH "https://api.hoody.com/api/v1/users/USER_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"alias":"new-alias","current_password":"SecureP@ss123","password":"NewP@ss456"}'
```

```
# Retry initial setup (claim free-tier server, create default project/container)
curl -s -X POST "https://api.hoody.com/api/v1/users/me/retry-setup" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

#### 4.2 Activity Logs

```
# Get activity logs
curl -s "https://api.hoody.com/api/v1/users/auth/activity" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Get activity storage stats
curl -s "https://api.hoody.com/api/v1/users/auth/activity/stats" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

---

### 5. Projects

Projects are logical groupings for containers, networks, and shared configurations.

#### 5.1 List and Create Projects

```
# List all projects you own or have permissions for
curl -s "https://api.hoody.com/api/v1/projects/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Create a new project
curl -s -X POST "https://api.hoody.com/api/v1/projects/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"alias":"my-production-app"}'
```

#### 5.2 Read, Update, Delete Projects

```
# Get project details
curl -s "https://api.hoody.com/api/v1/projects/PROJECT_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Update project (alias, color, quotas)
curl -s -X PATCH "https://api.hoody.com/api/v1/projects/PROJECT_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"alias":"renamed-project","color":"#3366ff"}'
```

```
# Delete project (permanently destroys all associated resources)
curl -s -X DELETE "https://api.hoody.com/api/v1/projects/PROJECT_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Get project stats (aggregated resource usage for all containers)
curl -s "https://api.hoody.com/api/v1/projects/PROJECT_ID/stats" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

#### 5.3 Project Permissions

```
# List all users with access to a project
curl -s "https://api.hoody.com/api/v1/projects/PROJECT_ID/permissions" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Grant access (read, edit, or delete permission level)
curl -s -X POST "https://api.hoody.com/api/v1/projects/PROJECT_ID/permissions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"user_id":"TARGET_USER_ID","level":"edit"}'
```

```
# Change permission level
curl -s -X PATCH "https://api.hoody.com/api/v1/projects/PROJECT_ID/permissions/PERMISSION_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"level":"read"}'
```

```
# Revoke access
curl -s -X DELETE "https://api.hoody.com/api/v1/projects/PROJECT_ID/permissions/PERMISSION_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

---

### 6. Containers

#### 6.1 List and Create Containers

```
# List containers in a project
curl -s "https://api.hoody.com/api/v1/projects/PROJECT_ID/containers" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# List all containers across all projects
curl -s "https://api.hoody.com/api/v1/containers/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Create a container in a project
curl -s -X POST "https://api.hoody.com/api/v1/projects/PROJECT_ID/containers" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"image":"ubuntu-22.04","alias":"web-server"}'
```

#### 6.2 Container Operations

```
# Get container details
curl -s "https://api.hoody.com/api/v1/containers/CONTAINER_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Update container
curl -s -X PATCH "https://api.hoody.com/api/v1/containers/CONTAINER_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"alias":"renamed-server"}'
```

```
# Delete container
curl -s -X DELETE "https://api.hoody.com/api/v1/containers/CONTAINER_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Start container
curl -s -X POST "https://api.hoody.com/api/v1/containers/CONTAINER_ID/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{}'
```

```
# Stop container
curl -s -X POST "https://api.hoody.com/api/v1/containers/CONTAINER_ID/stop" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{}'
```

```
# Restart container
curl -s -X POST "https://api.hoody.com/api/v1/containers/CONTAINER_ID/restart" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{}'
```

```
# Get container stats (CPU, memory, disk, network)
curl -s "https://api.hoody.com/api/v1/containers/CONTAINER_ID/stats" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Get container status logs
curl -s "https://api.hoody.com/api/v1/containers/CONTAINER_ID/status-logs" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

#### 6.3 Container Copy and Sync

```
# Copy a container (runs async, new container starts on success)
curl -s -X POST "https://api.hoody.com/api/v1/containers/CONTAINER_ID/copy" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{}'
```

```
# Incremental sync (only works on containers created via copy)
curl -s -X POST "https://api.hoody.com/api/v1/containers/CONTAINER_ID/sync" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{}'
```

#### 6.4 Container Authorization Claim

```
# Issue a signed portable authorization claim (ED25519-signed)
curl -s -X POST "https://api.hoody.com/api/v1/containers/CONTAINER_ID/authorize" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{}'
```

Returns a `container_claim` credential proving user identity and container authorization.

---

### 7. Container Environment Variables

```
# Get all environment variables
curl -s "https://api.hoody.com/api/v1/containers/CONTAINER_ID/env" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Merge environment variables (existing keys updated, new keys added)
curl -s -X PUT "https://api.hoody.com/api/v1/containers/CONTAINER_ID/env" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"DATABASE_URL":"postgres://localhost/mydb","API_KEY":"sk-1234"}'
```

```
# Set a single environment variable
curl -s -X PUT "https://api.hoody.com/api/v1/containers/CONTAINER_ID/env/MY_VAR" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"value":"my-value"}'
```

```
# Delete a single environment variable (idempotent)
curl -s -X DELETE "https://api.hoody.com/api/v1/containers/CONTAINER_ID/env/MY_VAR" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

**Note**: Keys starting with `HOODY_` are reserved and cannot be set or deleted.

---

### 8. Container Firewall

#### 8.1 View Rules

```
# Get all firewall rules (ingress + egress)
curl -s "https://api.hoody.com/api/v1/containers/CONTAINER_ID/firewall/rules" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

#### 8.2 Ingress Rules (Inbound Traffic)

```
# Add ingress rule
curl -s -X POST "https://api.hoody.com/api/v1/containers/CONTAINER_ID/firewall/ingress" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"protocol":"tcp","port":443,"source":"0.0.0.0/0","action":"allow"}'
```

```
# Toggle ingress rule (enable/disable without deleting)
curl -s -X PATCH "https://api.hoody.com/api/v1/containers/CONTAINER_ID/firewall/ingress" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"filters":{"protocol":"tcp","port":443},"state":"disabled"}'
```

```
# Remove specific ingress rules
curl -s -X DELETE "https://api.hoody.com/api/v1/containers/CONTAINER_ID/firewall/ingress" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"filters":{"protocol":"tcp","port":443}}'
```

#### 8.3 Egress Rules (Outbound Traffic)

```
# Add egress rule
curl -s -X POST "https://api.hoody.com/api/v1/containers/CONTAINER_ID/firewall/egress" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"protocol":"tcp","port":443,"destination":"0.0.0.0/0","action":"allow"}'
```

```
# Remove all egress rules
curl -s -X DELETE "https://api.hoody.com/api/v1/containers/CONTAINER_ID/firewall/egress" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"all":true}'
```

#### 8.4 Reset Firewall

```
# Reset to open state (deletes ACL, detaches bridge)
curl -s -X POST "https://api.hoody.com/api/v1/containers/CONTAINER_ID/firewall/reset" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{}'
```

---

### 9. Container Network

```
# Get network configuration and status
curl -s "https://api.hoody.com/api/v1/containers/CONTAINER_ID/network" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Configure network proxy/blocking
curl -s -X PUT "https://api.hoody.com/api/v1/containers/CONTAINER_ID/network" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"mode":"proxy","blocking":false}'
```

```
# Start network proxy/blocking service
curl -s -X POST "https://api.hoody.com/api/v1/containers/CONTAINER_ID/network/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{}'
```

```
# Stop network proxy/blocking service
curl -s -X POST "https://api.hoody.com/api/v1/containers/CONTAINER_ID/network/stop" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{}'
```

```
# Remove network configuration entirely
curl -s -X DELETE "https://api.hoody.com/api/v1/containers/CONTAINER_ID/network" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

---

### 10. Container Snapshots

```
# List all snapshots
curl -s "https://api.hoody.com/api/v1/containers/CONTAINER_ID/snapshots" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Create a snapshot
curl -s -X POST "https://api.hoody.com/api/v1/containers/CONTAINER_ID/snapshots" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"name":"pre-deploy-v2"}'
```

```
# Restore from a snapshot
curl -s -X PUT "https://api.hoody.com/api/v1/containers/CONTAINER_ID/snapshots/pre-deploy-v2" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{}'
```

```
# Update snapshot alias
curl -s -X PATCH "https://api.hoody.com/api/v1/containers/CONTAINER_ID/snapshots/pre-deploy-v2/alias" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"alias":"Pre-deployment backup v2"}'
```

---

### 11. Container Images

```
# Browse public images
curl -s "https://api.hoody.com/api/v1/images/public" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Get public image details
curl -s "https://api.hoody.com/api/v1/images/public/IMAGE_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Get image icon
curl -s "https://api.hoody.com/api/v1/images/IMAGE_ID/icon" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# List user's imported/purchased images
curl -s "https://api.hoody.com/api/v1/images/user" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Import a free public image
curl -s -X POST "https://api.hoody.com/api/v1/images/import/IMAGE_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{}'
```

```
# Purchase a paid image
curl -s -X POST "https://api.hoody.com/api/v1/images/purchase/IMAGE_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{}'
```

```
# Rate an image (0-5 stars)
curl -s -X POST "https://api.hoody.com/api/v1/images/rate/IMAGE_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"rating":5}'
```

---

### 12. Proxy Permissions (Project Level)

```
# Get project proxy permissions configuration
curl -s "https://api.hoody.com/api/v1/projects/PROJECT_ID/proxy/permissions" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Replace entire proxy permissions config
curl -s -X PUT "https://api.hoody.com/api/v1/projects/PROJECT_ID/proxy/permissions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{}'
```

```
# Update default access policy (allow or deny)
curl -s -X PATCH "https://api.hoody.com/api/v1/projects/PROJECT_ID/proxy/permissions/default" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"default":"deny"}'
```

```
# Enable/disable proxy entirely
curl -s -X PATCH "https://api.hoody.com/api/v1/projects/PROJECT_ID/proxy/permissions/state" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"enabled":true}'
```

```
# Delete all proxy permissions (reverts to open access)
curl -s -X DELETE "https://api.hoody.com/api/v1/projects/PROJECT_ID/proxy/permissions" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

#### 12.1 Group-Specific Proxy Permissions (Project)

```
# Delete a group
curl -s -X DELETE "https://api.hoody.com/api/v1/projects/PROJECT_ID/proxy/permissions/groups/GROUP_NAME" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Set IP-based auth for a group
curl -s -X PUT "https://api.hoody.com/api/v1/projects/PROJECT_ID/proxy/permissions/groups/GROUP_NAME/ip" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"allowed_ips":["192.168.1.0/24"]}'
```

```
# Set JWT-based auth for a group
curl -s -X PUT "https://api.hoody.com/api/v1/projects/PROJECT_ID/proxy/permissions/groups/GROUP_NAME/jwt" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"jwt_config":{}}'
```

```
# Set password-based auth for a group
curl -s -X PUT "https://api.hoody.com/api/v1/projects/PROJECT_ID/proxy/permissions/groups/GROUP_NAME/password" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"username":"admin","password":"secret"}'
```

```
# Set token-based auth for a group
curl -s -X PUT "https://api.hoody.com/api/v1/projects/PROJECT_ID/proxy/permissions/groups/GROUP_NAME/token" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"tokens":["tok_abc123"]}'
```

#### 12.2 Program Permissions (Project)

```
# Update permissions for a group
curl -s -X PATCH "https://api.hoody.com/api/v1/projects/PROJECT_ID/proxy/permissions/permissions/GROUP_NAME" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{}'
```

```
# Delete a specific program permission
curl -s -X DELETE "https://api.hoody.com/api/v1/projects/PROJECT_ID/proxy/permissions/permissions/GROUP_NAME/PROGRAM_NAME" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

---

### 13. Proxy Permissions (Container Level)

Container-level proxy permissions mirror project-level but apply to individual containers. They use optimistic concurrency via `If-Match` headers.

```
# Get container proxy permissions
curl -s "https://api.hoody.com/api/v1/containers/CONTAINER_ID/proxy/permissions" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Replace container proxy permissions (requires If-Match with file_version)
curl -s -X PUT "https://api.hoody.com/api/v1/containers/CONTAINER_ID/proxy/permissions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "If-Match: file:v1" \
  -d '{}'
```

The same group-level and program-level sub-endpoints exist for containers as for projects (IP, JWT, password, token auth; permission cells).

---

### 14. Proxy Hooks

Hooks allow custom script execution on proxy requests, with first-match-wins ordering.

```
# Get all hooks grouped by service
curl -s "https://api.hoody.com/api/v1/containers/CONTAINER_ID/proxy/hooks" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Get hooks for a specific service
curl -s "https://api.hoody.com/api/v1/containers/CONTAINER_ID/proxy/hooks/SERVICE_NAME" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Create a hook (requires If-Match)
curl -s -X POST "https://api.hoody.com/api/v1/containers/CONTAINER_ID/proxy/hooks/SERVICE_NAME" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "If-Match: file:v1" \
  -d '{"match":{"path":"/api/*"},"script":"console.log(request)"}'
```

```
# Update a hook (full replace, preserves id and position)
curl -s -X PATCH "https://api.hoody.com/api/v1/containers/CONTAINER_ID/proxy/hooks/SERVICE_NAME/HOOK_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "If-Match: file:v2" \
  -d '{"match":{"path":"/api/*"},"script":"console.log(updated)"}'
```

```
# Move a hook to a new position
curl -s -X PATCH "https://api.hoody.com/api/v1/containers/CONTAINER_ID/proxy/hooks/SERVICE_NAME/HOOK_ID/position" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "If-Match: file:v2" \
  -d '{"position":0}'
```

```
# Delete a single hook
curl -s -X DELETE "https://api.hoody.com/api/v1/containers/CONTAINER_ID/proxy/hooks/SERVICE_NAME/HOOK_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "If-Match: file:v2"
```

```
# Delete all hooks for a service
curl -s -X DELETE "https://api.hoody.com/api/v1/containers/CONTAINER_ID/proxy/hooks/SERVICE_NAME" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "If-Match: file:v2"
```

---

### 15. Proxy Discovery and Settings

```
# Get proxy settings (enable_proxy, default policy) with ETag
curl -s "https://api.hoody.com/api/v1/containers/CONTAINER_ID/proxy/settings" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Update proxy settings (requires If-Match)
curl -s -X PATCH "https://api.hoody.com/api/v1/containers/CONTAINER_ID/proxy/settings" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "If-Match: file:v1" \
  -d '{"enable_proxy":true,"default":"allow"}'
```

```
# Get all defined group names with auth-rule counts
curl -s "https://api.hoody.com/api/v1/containers/CONTAINER_ID/proxy/groups" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Get all service names referenced by permissions or hooks
curl -s "https://api.hoody.com/api/v1/containers/CONTAINER_ID/proxy/services" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Debug view for a specific service (non-authoritative)
curl -s "https://api.hoody.com/api/v1/containers/CONTAINER_ID/proxy/services/SERVICE_NAME" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

---

### 16. Proxy Aliases

Custom domain aliases that mask the real Project/Container IDs in URLs.

```
# List all proxy aliases
curl -s "https://api.hoody.com/api/v1/proxy/aliases" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Create a custom alias
curl -s -X POST "https://api.hoody.com/api/v1/proxy/aliases" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"alias":"my-app","container_id":"CONTAINER_ID","project_id":"PROJECT_ID"}'
```

```
# Get alias details
curl -s "https://api.hoody.com/api/v1/proxy/aliases/ALIAS_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Update alias
curl -s -X PATCH "https://api.hoody.com/api/v1/proxy/aliases/ALIAS_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"alias":"renamed-app"}'
```

```
# Enable/disable alias without deleting
curl -s -X PATCH "https://api.hoody.com/api/v1/proxy/aliases/ALIAS_ID/state" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"enabled":false}'
```

```
# Delete alias (immediately returns 404)
curl -s -X DELETE "https://api.hoody.com/api/v1/proxy/aliases/ALIAS_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

---

### 17. Storage Shares

Share directories between containers or to entire projects.

#### 17.1 Create and Manage Shares

```
# List shares from a source container
curl -s "https://api.hoody.com/api/v1/containers/CONTAINER_ID/storage/shares" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Share a directory to a target container
curl -s -X POST "https://api.hoody.com/api/v1/containers/CONTAINER_ID/storage/shares" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"path":"/data/shared","target_container_id":"TARGET_CONTAINER_ID","mount_path":"/mnt/shared","mode":"rw"}'
```

```
# Get share details
curl -s "https://api.hoody.com/api/v1/containers/CONTAINER_ID/storage/shares/SHARE_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Update share properties
curl -s -X PATCH "https://api.hoody.com/api/v1/containers/CONTAINER_ID/storage/shares/SHARE_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"mode":"ro"}'
```

```
# Delete a share (automatically unmounts from targets)
curl -s -X DELETE "https://api.hoody.com/api/v1/storage/shares/SHARE_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

#### 17.2 Incoming Shares

```
# Get all incoming shares for a container
curl -s "https://api.hoody.com/api/v1/containers/CONTAINER_ID/storage/incoming" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Get all incoming shares across all projects
curl -s "https://api.hoody.com/api/v1/storage/incoming" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Get all shares you created across all containers
curl -s "https://api.hoody.com/api/v1/storage/shares" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Enable/disable mounting of an incoming share
curl -s -X PATCH "https://api.hoody.com/api/v1/containers/CONTAINER_ID/storage/incoming/SHARE_ID/mount" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"enabled":true}'
```

---

### 18. User Vault

Encrypted key-value storage for secrets, credentials, and configuration.

```
# Get vault usage statistics
curl -s "https://api.hoody.com/api/v1/vault/stats" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# List all vault keys (metadata only, no values)
curl -s "https://api.hoody.com/api/v1/vault/keys" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Get a specific key-value pair
curl -s "https://api.hoody.com/api/v1/vault/keys/my-secret-key" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Create or update a key-value pair
curl -s -X PUT "https://api.hoody.com/api/v1/vault/keys/my-secret-key" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"value":"encrypted_or_plain_secret_value"}'
```

```
# Delete a specific key (permanent, cannot be undone)
curl -s -X DELETE "https://api.hoody.com/api/v1/vault/keys/my-secret-key" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# DANGER: Delete ALL keys in vault (permanent, cannot be undone)
curl -s -X DELETE "https://api.hoody.com/api/v1/vault" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

---

### 19. Wallet and Billing

#### 19.1 Balances and Transfers

```
# Get all balances
curl -s "https://api.hoody.com/api/v1/wallet/balances" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Get general balance
curl -s "https://api.hoody.com/api/v1/wallet/balances/general" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Get AI credit balance
curl -s "https://api.hoody.com/api/v1/wallet/balances/ai" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Transfer from general balance to AI credits
curl -s -X POST "https://api.hoody.com/api/v1/wallet/transfers" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"amount":"10.00"}'
```

```
# Get AI fee history
curl -s "https://api.hoody.com/api/v1/wallet/ai-fee-history" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

#### 19.2 Payment Methods

```
# List payment methods
curl -s "https://api.hoody.com/api/v1/wallet/payment-methods/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Add a payment method
curl -s -X POST "https://api.hoody.com/api/v1/wallet/payment-methods/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{}'
```

```
# Get a specific payment method
curl -s "https://api.hoody.com/api/v1/wallet/payment-methods/PAYMENT_METHOD_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Update a payment method
curl -s -X PATCH "https://api.hoody.com/api/v1/wallet/payment-methods/PAYMENT_METHOD_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{}'
```

```
# Set as default payment method
curl -s -X PUT "https://api.hoody.com/api/v1/wallet/payment-methods/PAYMENT_METHOD_ID/default" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{}'
```

```
# Delete a payment method
curl -s -X DELETE "https://api.hoody.com/api/v1/wallet/payment-methods/PAYMENT_METHOD_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

#### 19.3 Payments and Stripe Integration

```
# Process a payment
curl -s -X POST "https://api.hoody.com/api/v1/wallet/payments/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"payment_method_id":"PM_ID","amount":"25.00"}'
```

```
# Get payment status
curl -s "https://api.hoody.com/api/v1/wallet/payments/PAYMENT_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Create Stripe Checkout session (redirect user to checkout_url)
curl -s -X POST "https://api.hoody.com/api/v1/wallet/payments/stripe/checkout" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"amount":"50.00"}'
```

```
# List Stripe payment intents (newest first)
curl -s "https://api.hoody.com/api/v1/wallet/payments/stripe/intents" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Get a specific Stripe payment intent (poll after checkout redirect)
curl -s "https://api.hoody.com/api/v1/wallet/payments/stripe/intents/INTENT_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

#### 19.4 Transactions and Invoices

```
# List transactions
curl -s "https://api.hoody.com/api/v1/wallet/transactions" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Get transaction details
curl -s "https://api.hoody.com/api/v1/wallet/transactions/TRANSACTION_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# List invoices
curl -s "https://api.hoody.com/api/v1/wallet/invoices/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Download invoice as PDF
curl -s "https://api.hoody.com/api/v1/wallet/invoices/INVOICE_ID/pdf" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --output invoice.pdf
```

```
# Generate invoice for a transaction
curl -s -X POST "https://api.hoody.com/api/v1/wallet/invoices/generate/TRANSACTION_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{}'
```

---

### 20. Notifications

```
# Get public notifications (no auth required)
curl -s "https://api.hoody.com/api/v1/notifications/public"
```

```
# Get all user notifications (global + targeted)
curl -s "https://api.hoody.com/api/v1/notifications/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Mark a notification as read
curl -s -X PATCH "https://api.hoody.com/api/v1/notifications/NOTIFICATION_ID/read" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{}'
```

```
# Mark all notifications as read
curl -s -X PATCH "https://api.hoody.com/api/v1/notifications/read-all" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{}'
```

---

### 21. Events

```
# Get event history (max 500 per page)
curl -s "https://api.hoody.com/api/v1/events" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Get event statistics
curl -s "https://api.hoody.com/api/v1/events/stats" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Get event details
curl -s "https://api.hoody.com/api/v1/events/EVENT_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Delete multiple events by filter
curl -s -X DELETE "https://api.hoody.com/api/v1/events" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{}'
```

```
# Delete a specific event
curl -s -X DELETE "https://api.hoody.com/api/v1/events/EVENT_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Cleanup old events by retention period
curl -s -X POST "https://api.hoody.com/api/v1/events/cleanup" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"retention_days":30}'
```

---

### 22. AI Models

```
# Get available AI models catalog
curl -s "https://api.hoody.com/api/v1/ai/models" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

Returns cached catalog with Hoody pricing. Provider details are intentionally not exposed.

---

### 23. Meta and Utilities

```
# Get ED25519 public key(s) used by Hoody for signing
curl -s "https://api.hoody.com/api/v1/meta/public-key"
```

Used for verifying `X-Hoody-Signature` headers, identity claims, and container authorization claims.

```
# Get social stats (GitHub stars, Telegram/Discord/X/LinkedIn followers)
curl -s "https://api.hoody.com/api/v1/meta/social-stats"
```

```
# Get caller IP info (geolocation and network details)
curl -s "https://api.hoody.com/api/v1/ip"
```

---

### 24. Realms

```
# Get all unique realm IDs from your resources
curl -s "https://api.hoody.com/api/v1/realms/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

Returns deduplicated list of 24-hex realm identifiers from your projects, containers, servers (via pools), and auth tokens. Requires `resources.realms` permission.

---

### 25. Pools

Pools enable team collaboration with role-based membership.

#### 25.1 Pool Management

```
# List pools you own or are a member of
curl -s "https://api.hoody.com/api/v1/pools" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Create a new pool
curl -s -X POST "https://api.hoody.com/api/v1/pools" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"name":"engineering-team"}'
```

```
# Get pool details
curl -s "https://api.hoody.com/api/v1/pools/POOL_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Update pool details (owner only)
curl -s -X PATCH "https://api.hoody.com/api/v1/pools/POOL_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"name":"renamed-team"}'
```

```
# Delete pool (owner only, cannot delete default pool)
curl -s -X DELETE "https://api.hoody.com/api/v1/pools/POOL_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

#### 25.2 Pool Members

```
# Invite a user to the pool (admin+ required)
curl -s -X POST "https://api.hoody.com/api/v1/pools/POOL_ID/members" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"user_id":"TARGET_USER_ID","role":"member"}'
```

```
# Update member role (owner only)
curl -s -X PATCH "https://api.hoody.com/api/v1/pools/POOL_ID/members/USER_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"role":"admin"}'
```

```
# Remove member from pool (admin+ required)
curl -s -X DELETE "https://api.hoody.com/api/v1/pools/POOL_ID/members/USER_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

#### 25.3 Pool Invitations

```
# Get pending invitations
curl -s "https://api.hoody.com/api/v1/pools/invitations/pending" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Accept an invitation
curl -s -X POST "https://api.hoody.com/api/v1/pools/POOL_ID/accept" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{}'
```

```
# Reject an invitation
curl -s -X POST "https://api.hoody.com/api/v1/pools/POOL_ID/reject" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{}'
```

---

### 26. Server Rental

#### 26.1 Browse and Rent Servers

```
# Get available servers for rental
curl -s "https://api.hoody.com/api/v1/servers/available" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Rent a server
curl -s -X POST "https://api.hoody.com/api/v1/servers/SERVER_ID/rent" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"duration_days":30}'
```

```
# List your rented servers (alias for rentals)
curl -s "https://api.hoody.com/api/v1/servers" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Get specific rented server details
curl -s "https://api.hoody.com/api/v1/servers/SERVER_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

#### 26.2 Rentals

```
# List all rentals
curl -s "https://api.hoody.com/api/v1/rentals" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Get rental details
curl -s "https://api.hoody.com/api/v1/rentals/RENTAL_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Extend a rental
curl -s -X POST "https://api.hoody.com/api/v1/rentals/RENTAL_ID/extend" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"duration_days":7}'
```

#### 26.3 Server Commands

```
# Get available commands for a server
curl -s "https://api.hoody.com/api/v1/servers/SERVER_ID/available-commands" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```
# Execute a command on a server
curl -s -X POST "https://api.hoody.com/api/v1/servers/SERVER_ID/execute-command" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"command":"restart"}'
```

---

## Advanced Operations

### Full Container Lifecycle

Complete workflow from project creation to running container with networking, firewall, and proxy.

```
# 1. Create project
PROJECT=$(curl -s -X POST "https://api.hoody.com/api/v1/projects/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"alias":"production-stack"}')
PROJECT_ID=$(echo "$PROJECT" | jq -r '.data.id')

# 2. Create container in project
CONTAINER=$(curl -s -X POST "https://api.hoody.com/api/v1/projects/$PROJECT_ID/containers" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"image":"ubuntu-22.04","alias":"api-server"}')
CONTAINER_ID=$(echo "$CONTAINER" | jq -r '.data.id')

# 3. Set environment variables
curl -s -X PUT "https://api.hoody.com/api/v1/containers/$CONTAINER_ID/env" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"NODE_ENV":"production","PORT":"3000"}'

# 4. Configure firewall - allow HTTPS and SSH only
curl -s -X POST "https://api.hoody.com/api/v1/containers/$CONTAINER_ID/firewall/ingress" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"protocol":"tcp","port":443,"source":"0.0.0.0/0","action":"allow"}'

curl -s -X POST "https://api.hoody.com/api/v1/containers/$CONTAINER_ID/firewall/ingress" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"protocol":"tcp","port":22,"source":"YOUR_IP/32","action":"allow"}'

# 5. Start network proxy
curl -s -X POST "https://api.hoody.com/api/v1/containers/$CONTAINER_ID/network/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{}'

# 6. Configure proxy settings
curl -s -X PATCH "https://api.hoody.com/api/v1/containers/$CONTAINER_ID/proxy/settings" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "If-Match: file:v0" \
  -d '{"enable_proxy":true,"default":"deny"}'

# 7. Create custom alias
curl -s -X POST "https://api.hoody.com/api/v1/proxy/aliases" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d "{\"alias\":\"api\",\"container_id\":\"$CONTAINER_ID\",\"project_id\":\"$PROJECT_ID\"}"

# 8. Create a snapshot before first deploy
curl -s -X POST "https://api.hoody.com/api/v1/containers/$CONTAINER_ID/snapshots" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"name":"clean-install"}'

# 9. Verify with stats
curl -s "https://api.hoody.com/api/v1/containers/$CONTAINER_ID/stats" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Storage Sharing Between Containers

Share a data directory from one container to another within a project.

```
# 1. Create share from source to target
SHARE=$(curl -s -X POST "https://api.hoody.com/api/v1/containers/SOURCE_CONTAINER_ID/storage/shares" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"path":"/data/uploads","target_container_id":"TARGET_CONTAINER_ID","mount_path":"/mnt/uploads","mode":"rw"}')

# 2. Verify share on target's incoming list
curl -s "https://api.hoody.com/api/v1/containers/TARGET_CONTAINER_ID/storage/incoming" \
  -H "Authorization: Bearer YOUR_TOKEN"

# 3. Target owner can enable/disable mount
curl -s -X PATCH "https://api.hoody.com/api/v1/containers/TARGET_CONTAINER_ID/storage/incoming/SHARE_ID/mount" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TARGET_OWNER_TOKEN" \
  -d '{"enabled":true}'
```

### Team Collaboration Setup

Set up a pool with members and shared project access.

```
# 1. Create pool
POOL=$(curl -s -X POST "https://api.hoody.com/api/v1/pools" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"name":"dev-team"}')
POOL_ID=$(echo "$POOL" | jq -r '.data.id')

# 2. Invite team member
curl -s -X POST "https://api.hoody.com/api/v1/pools/$POOL_ID/members" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"user_id":"TEAM_MEMBER_ID","role":"member"}'

# 3. Grant project access to team member
curl -s -X POST "https://api.hoody.com/api/v1/projects/PROJECT_ID/permissions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"user_id":"TEAM_MEMBER_ID","level":"edit"}'

# 4. Verify pending invitations
curl -s "https://api.hoody.com/api/v1/pools/invitations/pending" \
  -H "Authorization: Bearer TEAM_MEMBER_TOKEN"
```

### Server Rental and Container Deployment

Rent a dedicated server and deploy containers to it.

```
# 1. Browse available servers
curl -s "https://api.hoody.com/api/v1/servers/available" \
  -H "Authorization: Bearer YOUR_TOKEN"

# 2. Rent a server
curl -s -X POST "https://api.hoody.com/api/v1/servers/SERVER_ID/rent" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"duration_days":30}'

# 3. Check available commands
curl -s "https://api.hoody.com/api/v1/servers/SERVER_ID/available-commands" \
  -H "Authorization: Bearer YOUR_TOKEN"

# 4. Extend rental if needed
curl -s -X POST "https://api.hoody.com/api/v1/rentals/RENTAL_ID/extend" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"duration_days":14}'
```

### Copy and Sync Container Workflow

Create a staging copy of a production container, sync changes incrementally.

```
# 1. Copy production container to staging
COPY=$(curl -s -X POST "https://api.hoody.com/api/v1/containers/PROD_CONTAINER_ID/copy" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{}')
STAGING_ID=$(echo "$COPY" | jq -r '.data.id')

# 2. Wait for copy to complete (check status)
curl -s "https://api.hoody.com/api/v1/containers/$STAGING_ID" \
  -H "Authorization: Bearer YOUR_TOKEN"

# 3. Later: sync changes from production to staging
curl -s -X POST "https://api.hoody.com/api/v1/containers/$STAGING_ID/sync" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{}'
```

### Wallet Funding via Stripe

Fund account balance through Stripe Checkout.

```
# 1. Create Stripe Checkout session
CHECKOUT=$(curl -s -X POST "https://api.hoody.com/api/v1/wallet/payments/stripe/checkout" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"amount":"100.00"}')
CHECKOUT_URL=$(echo "$CHECKOUT" | jq -r '.data.checkout_url')

# 2. Redirect user to $CHECKOUT_URL in browser

# 3. After redirect back, poll payment intent status
curl -s "https://api.hoody.com/api/v1/wallet/payments/stripe/intents/INTENT_ID" \
  -H "Authorization: Bearer YOUR_TOKEN"

# 4. Verify balance credited
curl -s "https://api.hoody.com/api/v1/wallet/balances/general" \
  -H "Authorization: Bearer YOUR_TOKEN"

# 5. Transfer to AI credits if needed
curl -s -X POST "https://api.hoody.com/api/v1/wallet/transfers" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"amount":"25.00"}'
```

### Error Recovery Patterns

#### Retry After Stale If-Match

When proxy permissions/hooks return 412 (Precondition Failed), re-fetch the ETag and retry:

```
# 1. Get current version
CURRENT=$(curl -s "https://api.hoody.com/api/v1/containers/CONTAINER_ID/proxy/settings" \
  -H "Authorization: Bearer YOUR_TOKEN")
ETAG=$(echo "$CURRENT" | jq -r '.data.file_version')

# 2. Retry with correct ETag
curl -s -X PATCH "https://api.hoody.com/api/v1/containers/CONTAINER_ID/proxy/settings" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "If-Match: file:v$ETAG" \
  -d '{"enable_proxy":true}'
```

#### Project Deletion Cleanup

If project deletion partially fails, the project remains available for retry:

```
# Retry deletion
curl -s -X DELETE "https://api.hoody.com/api/v1/projects/PROJECT_ID" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

## Quick Reference

### Endpoint Groups Summary

| Resource Group | Base Path | Methods |
|---|---|---|
| **Auth - Login/Signup** | `/api/v1/auth/signup`, `/api/v1/users/auth/login` | POST |
| **Auth - OAuth** | `/api/v1/auth/github`, `/api/v1/auth/google` | GET |
| **Auth - Password** | `/api/v1/auth/forgot-password`, `/api/v1/auth/reset-password` | POST |
| **Auth - Email** | `/api/v1/auth/verify-email`, `/api/v1/auth/resend-verification` | POST |
| **Auth - Tokens** | `/api/v1/auth/tokens`, `/api/v1/auth/tokens/{id}` | GET, POST, PUT, PATCH, DELETE |
| **Auth - Token Realms** | `/api/v1/auth/tokens/{id}/add-realm`, `remove-realm` | POST |
| **Auth - Token Profiles** | `/api/v1/auth/tokens/me/public-profile`, `public-profiles/{key}` | GET, PUT, PATCH |
| **2FA** | `/api/v1/users/auth/2fa/*` | GET, POST, PUT, PATCH, DELETE |
| **Users** | `/api/v1/users/{id}`, `/api/v1/users/auth/me` | GET, PUT, PATCH |
| **Activity Logs** | `/api/v1/users/auth/activity` | GET |
| **Projects** | `/api/v1/projects/`, `/api/v1/projects/{id}` | GET, POST, PUT, PATCH, DELETE |
| **Project Permissions** | `/api/v1/projects/{id}/permissions` | GET, POST, PUT, PATCH, DELETE |
| **Project Proxy Perms** | `/api/v1/projects/{id}/proxy/permissions/*` | GET, PUT, PATCH, DELETE |
| **Project Stats** | `/api/v1/projects/{id}/stats` | GET |
| **Containers** | `/api/v1/containers/`, `/api/v1/containers/{id}` | GET, PUT, PATCH, DELETE |
| **Container Operations** | `/api/v1/containers/{id}/{operation}` | POST |
| **Container Copy/Sync** | `/api/v1/containers/{id}/copy`, `sync` | POST |
| **Container Authorize** | `/api/v1/containers/{id}/authorize` | POST |
| **Container Environment** | `/api/v1/containers/{id}/env` | GET, PUT, PATCH, DELETE |
| **Container Firewall** | `/api/v1/containers/{id}/firewall/*` | GET, POST, PATCH, DELETE |
| **Container Network** | `/api/v1/containers/{id}/network` | GET, PUT, PATCH, DELETE, POST |
| **Container Snapshots** | `/api/v1/containers/{id}/snapshots` | GET, POST, PUT, PATCH |
| **Container Stats** | `/api/v1/containers/{id}/stats`, `status-logs` | GET |
| **Container Proxy Perms** | `/api/v1/containers/{id}/proxy/permissions/*` | GET, PUT, PATCH, DELETE |
| **Container Proxy Hooks** | `/api/v1/containers/{id}/proxy/hooks/*` | GET, POST, PUT, PATCH, DELETE |
| **Container Proxy Settings** | `/api/v1/containers/{id}/proxy/settings`, `groups`, `services` | GET, PUT, PATCH |
| **Container Storage** | `/api/v1/containers/{id}/storage/*` | GET, POST, PATCH |
| **Images** | `/api/v1/images/*` | GET, POST |
| **Proxy Aliases** | `/api/v1/proxy/aliases`, `/api/v1/proxy/aliases/{id}` | GET, POST, PATCH, DELETE |
| **Vault** | `/api/v1/vault`, `/api/v1/vault/keys/{key}` | GET, PUT, PATCH, DELETE |
| **Notifications** | `/api/v1/notifications/` | GET, PUT, PATCH |
| **Events** | `/api/v1/events`, `/api/v1/events/{id}` | GET, POST, DELETE |
| **AI Models** | `/api/v1/ai/models` | GET |
| **Meta** | `/api/v1/meta/public-key`, `social-stats` | GET |
| **IP Info** | `/api/v1/ip` | GET |
| **Realms** | `/api/v1/realms/` | GET |
| **Pools** | `/api/v1/pools`, `/api/v1/pools/{id}` | GET, POST, PUT, PATCH, DELETE |
| **Pool Members** | `/api/v1/pools/{id}/members/{userId}` | POST, PUT, PATCH, DELETE |
| **Pool Invitations** | `/api/v1/pools/invitations/pending`, `accept`, `reject` | GET, POST |
| **Servers** | `/api/v1/servers`, `/api/v1/servers/{id}` | GET, POST |
| **Server Commands** | `/api/v1/servers/{serverId}/execute-command`, `available-commands` | GET, POST |
| **Rentals** | `/api/v1/rentals`, `/api/v1/rentals/{id}`, `extend` | GET, POST |
| **Wallet - Balances** | `/api/v1/wallet/balances`, `general`, `ai` | GET |
| **Wallet - Transfers** | `/api/v1/wallet/transfers` | POST |
| **Wallet - Payment Methods** | `/api/v1/wallet/payment-methods/*` | GET, POST, PUT, PATCH, DELETE |
| **Wallet - Payments** | `/api/v1/wallet/payments/*` | GET, POST |
| **Wallet - Stripe** | `/api/v1/wallet/payments/stripe/*` | GET, POST |
| **Wallet - Transactions** | `/api/v1/wallet/transactions`, `{id}` | GET |
| **Wallet - Invoices** | `/api/v1/wallet/invoices/*` | GET, POST |
| **Wallet - AI Fees** | `/api/v1/wallet/ai-fee-history` | GET |
| **Storage (Global)** | `/api/v1/storage/shares`, `/api/v1/storage/incoming` | GET, DELETE |

### Common Response Format

All API responses follow a consistent envelope:

```
{
  "success": true,
  "data": {},
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 150
  }
}
```

### Authentication Header Patterns

| Auth Type | Header Value | Used For |
|---|---|---|
| JWT Access Token | `Authorization: Bearer eyJhbG...` | All API calls after login |
| Auth Token | `Authorization: Bearer at_...` | Programmatic/CI access |
| Refresh Token | `Authorization: Bearer rt_...` | Token refresh only |
| Temp Token | `Authorization: Bearer tt_...` | 2FA verification step |

### Key Parameters

| Parameter | Where Used | Description |
|---|---|---|
| `If-Match` header | Proxy permissions, hooks, settings | Optimistic concurrency: `file:v{N}` |
| `id` path param | Most resource endpoints | 24-character resource identifier |
| `realm_id` body field | Token realm management | 24-hex character realm identifier |
| `operation` path param | Container operations | `start`, `stop`, `force-stop`, `restart`, `pause`, `resume` |

### Public Endpoints (No Auth Required)

- `GET /api/v1/auth/available-regions`
- `GET /api/v1/auth/github` (browser redirect)
- `GET /api/v1/auth/google` (browser redirect)
- `GET /api/v1/meta/public-key`
- `GET /api/v1/meta/social-stats`
- `GET /api/v1/notifications/public`
- `GET /api/v1/ip`