Skip to content
Hoody Documentation
Download Page (.md)

Hoody API

Section titled “Hoody API”

The Hoody API is your control plane. It’s how you create, configure, and orchestrate your infinite computers.

After reading The Vision, you understand Hoody’s philosophy. Now you need to understand how to actually use it. The Hoody API is where everything begins.

API Endpoints Summary

Section titled “API Endpoints Summary”

Official Technical Reference:

This Foundation page explains HOW the Hoody API works. For complete endpoint documentation, parameters, and responses:

Core Management:

Networking & Security:

Proxy & Routing:

Data & State:

Two APIs, Two Purposes

Section titled “Two APIs, Two Purposes”

Critical distinction: Hoody has TWO separate HTTP systems:

Hoody API (Platform Management)

https://api.hoody.icu

What it controls:

  • ✅ User authentication
  • ✅ Project creation
  • ✅ Container spawning
  • ✅ Network configuration
  • ✅ Firewall rules
  • ✅ Proxy aliases
  • ✅ Snapshots
  • ✅ Billing

Mental model: “The dashboard API”

Container Services (Hoody Kit)

https://{project}-{container}-terminal-1.node-us.containers.hoody.icu
https://{project}-{container}-display-1.node-us.containers.hoody.icu
https://{project}-{container}-files.node-us.containers.hoody.icu

What they provide:

  • ✅ Terminal execution
  • ✅ Desktop access
  • ✅ File operations
  • ✅ Database queries
  • ✅ Browser automation
  • ✅ Script execution
  • ✅ +12 more services

Mental model: “The actual computers”

The workflow:

  1. Use Hoody API to spawn a container
  2. Container gets URLs for all its services automatically
  3. Use those URLs to work with the container

The Hoody API creates the infrastructure. The container URLs ARE the infrastructure.

What the Hoody API Does

Section titled “What the Hoody API Does”

Think of it as the factory that builds your infinite computers:

1. Authentication & Users

Section titled “1. Authentication & Users”

Manage your account and create access credentials:

Terminal window
# Login as a user
hoody auth login --username your_username --password your_password


# Create long-lived API token for automation
hoody auth create --alias "my-automation-token" --expires-at "2027-04-12T00:00:00Z"


# Get current user profile
hoody auth profile current

See: Authentication → | API Reference →

2. Projects (Organization)

Section titled “2. Projects (Organization)”

Create folders to organize your containers:

Terminal window
# Create a project
hoody projects create --alias "my-project"


# List your projects
hoody projects list

See: Projects & Containers → | API Reference →

3. Containers (Spawn Computers)

Section titled “3. Containers (Spawn Computers)”

Create isolated computers with full capabilities:

Terminal window
# Spawn a container in a project
hoody containers create --project $PROJECT_ID --server-id $SERVER_ID --name "dev-env"


# Container URLs are automatically constructed:
# https://{project_id}-{container_id}-terminal-1.{server_name}.containers.hoody.icu
# https://{project_id}-{container_id}-display-1.{server_name}.containers.hoody.icu
# ... plus files, exec, workspaces, sqlite, cron, pipe, notifications, browser, code, daemon, tunnel, ssh, proxy, and dynamic http/https ports

Within 30 seconds: Container is running with all HTTP services live.

See: Container Lifecycle → | API Reference →

4. Networking & Security

Section titled “4. Networking & Security”

Configure how containers connect and communicate:

Terminal window
# Configure firewall rules
POST https://api.hoody.icu/api/v1/containers/{id}/firewall/ingress


# Route traffic through proxies/VPNs
PATCH https://api.hoody.icu/api/v1/containers/{id}/network


# Add an outbound firewall rule
POST https://api.hoody.icu/api/v1/containers/{id}/firewall/egress

See: Networking → | Firewall →

5. Proxy Configuration

Section titled “5. Proxy Configuration”

Make containers accessible with clean URLs:

Terminal window
# Create custom alias: my-app.$serverName.containers.hoody.icu
POST https://api.hoody.icu/api/v1/proxy/aliases


# Configure permissions
PATCH https://api.hoody.icu/api/v1/containers/{id}/proxy/permissions

See: Hoody Proxy → | Aliases →

6. Storage & Snapshots

Section titled “6. Storage & Snapshots”

Manage persistent data and state:

Terminal window
# Snapshot a container (capture complete state)
POST https://api.hoody.icu/api/v1/containers/{id}/snapshots


# Share directories between containers
POST https://api.hoody.icu/api/v1/containers/{id}/storage/shares

See: Snapshots → | Storage Shares →

7. Infrastructure Management

Section titled “7. Infrastructure Management”

Control servers and resources:

Terminal window
# List your active server rentals
GET https://api.hoody.icu/api/v1/rentals


# Manage container images
GET https://api.hoody.icu/api/v1/images/public

See: Servers → | Images →

The HTTP-First Design

Section titled “The HTTP-First Design”

The Hoody API is pure REST. This matters because:

AI Understands It Immediately

Section titled “AI Understands It Immediately”

LLMs were trained on HTTP. They know how to:

  • Construct JSON payloads
  • Make authenticated requests
  • Parse responses
  • Handle errors

No SDK needed. AI can orchestrate your entire infrastructure through HTTP:

// AI generates this WITHOUT special training
const workflow = [
  {
    description: "Create project for client",
    call: "POST https://api.hoody.icu/api/v1/projects/",
    body: { alias: "client-acme", color: "#3498db" }
  },
  {
    description: "Spawn 3 containers: frontend, backend, database",
    call: "POST https://api.hoody.icu/api/v1/projects/{project_id}/containers",
    repeat: 3,
    body: { server_id: "...", hoody_kit: true, dev_kit: true }
  },
  {
    description: "Configure firewall for database",
    call: "POST https://api.hoody.icu/api/v1/containers/{db_id}/firewall/ingress",
    body: { action: "allow", protocol: "tcp", destination_port: "5432", source: "{backend_ip}" }
  }
];


// AI executes via HTTP, no custom SDK
for (const step of workflow) {
  const response = await fetch(step.call, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.HOODY_TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(step.body)
  });
}

Any Language Works

Section titled “Any Language Works”

Every programming language has HTTP libraries:

Terminal window
# List all projects
hoody projects list

No SDK required. HTTP is the SDK. Works from JavaScript, Python, Go, Ruby, or any language with an HTTP client.

The Complete Workflow

Section titled “The Complete Workflow”

Here’s how everything connects:

1. AUTHENTICATE
   POST /api/v1/users/auth/login
   → Receive JWT tokens


2. CREATE AUTH TOKEN (for automation)
   POST /api/v1/auth/tokens
   → Get hdy_... token with IP whitelist, expiration
   → Use this in scripts/AI instead of user credentials


3. CREATE PROJECT
   POST /api/v1/projects/
   → Get project_id


4. SPAWN CONTAINER
   POST /api/v1/projects/{project_id}/containers
   → Get container_id, server_name
   → Container URLs automatically available:
     • https://{project_id}-{container_id}-terminal-1.{server_name}.containers.hoody.icu
     • https://{project_id}-{container_id}-display-1.{server_name}.containers.hoody.icu
     • https://{project_id}-{container_id}-exec-1.{server_name}.containers.hoody.icu
     • ... plus files, workspaces, sqlite, cron, pipe, notifications, browser, code, daemon, tunnel, ssh, proxy, and dynamic http/https ports


5. CONFIGURE (optional)
   PATCH /api/v1/containers/{id}/network         → Route through VPN
   POST /api/v1/containers/{id}/firewall/ingress → Add inbound firewall rule
   POST /api/v1/containers/{id}/firewall/egress  → Add outbound firewall rule
   POST /api/v1/proxy/aliases                    → Create custom domain


6. USE CONTAINER SERVICES
   # Now use the container URLs directly
   POST https://{project}-{container}-terminal-1.{server}.containers.hoody.icu/execute
   GET https://{project}-{container}-files.{server}.containers.hoody.icu/home/

Hoody API builds it. Container URLs use it.

API Organization

Section titled “API Organization”

The Hoody API is organized into logical groups:

Core Management

Section titled “Core Management”

Networking & Access

Section titled “Networking & Access”

Proxy & Routing

Section titled “Proxy & Routing”

Data & State

Section titled “Data & State”

Infrastructure

Section titled “Infrastructure”

Standard Patterns

Section titled “Standard Patterns”

Authentication

Section titled “Authentication”

Every request requires authentication:

Terminal window
# Login (stores credentials locally)
hoody auth login --username your_username --password your_password


# All subsequent commands use the stored token
hoody projects list
hoody containers list

For automation/AI: Use Auth Tokens (long-lived, IP-restricted, revocable). For user sessions: Use JWT from login (short-lived, refresh-able).

Error Handling

Section titled “Error Handling”

Standard error response:

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Detailed explanation of what went wrong"
}

Common status codes:

  • 400 - Bad Request (validation errors)
  • 401 - Unauthorized (missing/invalid token)
  • 403 - Forbidden (insufficient permissions)
  • 404 - Not Found (resource doesn’t exist)
  • 409 - Conflict (duplicate name, invalid state)
  • 500 - Internal Server Error

Pagination

Section titled “Pagination”

List endpoints support pagination:

Terminal window
GET /api/v1/projects?page=1&limit=20&sort_by=created_at&sort_order=desc

Response includes pagination metadata:

{
  "data": {
    "projects": [...],
    "pagination": {
      "total": 150,
      "page": 1,
      "limit": 20,
      "totalPages": 8
    }
  }
}

Filtering & Sorting

Section titled “Filtering & Sorting”

Many endpoints support filtering:

Terminal window
# Filter containers by realm
GET /api/v1/containers?realm_id=507f1f77bcf86cd799439011


# Filter by status
GET /api/v1/containers?status=running


# Sort by creation date
GET /api/v1/projects?sort_by=created_at&sort_order=desc

Why HTTP for Platform Management?

Section titled “Why HTTP for Platform Management?”

Traditional platforms use:

  • CLI tools (installed binaries, version conflicts)
  • Custom SDKs (language-specific, maintenance burden)
  • Complex protocols (proprietary, hard to debug)

Hoody uses pure HTTP:

  • ✅ Works from any language, any device
  • ✅ AI agents understand it natively
  • ✅ Curl-able, script-able, browser-based
  • ✅ Observable, debuggable, auditable
  • ✅ Compose-able with any HTTP service

Example: AI orchestrates infrastructure without SDK:

// AI generates infrastructure workflow
async function deployClientProject(clientName) {
  const token = process.env.HOODY_TOKEN;
  const headers = {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  };


  // 1. Create project
  const project = await fetch('https://api.hoody.icu/api/v1/projects/', {
    method: 'POST',
    headers,
    body: JSON.stringify({
      alias: `client-${clientName}`,
      color: '#3498db',
      max_containers: 50
    })
  }).then(r => r.json());


  // 2. Spawn 3 containers (frontend, backend, database)
  const containers = await Promise.all([
    'frontend', 'backend', 'database'
  ].map(name =>
    fetch(`https://api.hoody.icu/api/v1/projects/${project.data.id}/containers`, {
      method: 'POST',
      headers,
      body: JSON.stringify({
        name,
        server_id: 'your-server-id',
        hoody_kit: true,
        dev_kit: true
      })
    }).then(r => r.json())
  ));


  // 3. Create production alias
  await fetch('https://api.hoody.icu/api/v1/proxy/aliases', {
    method: 'POST',
    headers,
    body: JSON.stringify({
      container_id: containers[0].data.id,
      alias: `${clientName}-app`,
      program: 'http',
      index: 1
    })
  });


  // 4. Configure firewall for database
  await fetch(`https://api.hoody.icu/api/v1/containers/${containers[2].data.id}/firewall/ingress`, {
    method: 'POST',
    headers,
    body: JSON.stringify({
      action: 'allow',
      protocol: 'tcp',
      destination_port: '5432',
      source: `${containers[1].data.ipv4}/32`,
      description: 'Allow backend to database'
    })
  });


  return {
    projectId: project.data.id,
    containers: containers.map(c => ({
      name: c.data.name,
      terminalUrl: `https://${project.data.id}-${c.data.id}-terminal-1.${c.data.server_name}.containers.hoody.icu`,
      displayUrl: `https://${project.data.id}-${c.data.id}-display-1.${c.data.server_name}.containers.hoody.icu`
    }))
  };
}

AI needs zero training. It just uses HTTP.

API Base URL

Section titled “API Base URL”

Global API:

https://api.hoody.icu

Realm-Scoped API (for multi-tenant isolation):

https://{realmId}.api.hoody.icu

When you use a realm-scoped URL:

  • The subdomain realm must be a 24-char hex ID
  • Read operations are scoped to resources in that realm
  • Create/update operations preserve or merge that realm where supported
  • Container creation also requires the target project to already belong to that realm
  • API tokens can be restricted to specific realms
  • Realm-restricted tokens can bootstrap via GET /api/v1/auth/tokens/me on base host
  • Perfect for multi-tenant SaaS architectures

See: Realms → for realm-based API isolation.

Response Format

Section titled “Response Format”

All responses follow this structure:

{
  "statusCode": 200,
  "message": "Human-readable success message",
  "data": {
    // The actual response data
  }
}

Errors include details:

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Container name must be unique within project",
  "data": {
    "field": "name",
    "conflict": "staging-api"
  }
}

Getting Started

Section titled “Getting Started”

Your first API calls:

POST Login with username and password to get JWT access token
/api/v1/users/auth/login
Click "Run" to execute the request

Gives you: JWT access token

That’s it. In 4 API calls, you have a running computer with terminal, display, files, database, and 14 more HTTP services.

Useful Questions

Section titled “Useful Questions”

What’s the difference between Hoody API and container service URLs?

Section titled “What’s the difference between Hoody API and container service URLs?”

The Hoody API (api.hoody.icu) manages your infrastructure—creating containers, configuring networks, managing billing. Container service URLs ({project}-{container}-terminal-1.{server}.containers.hoody.icu) are the actual computers you use—execute commands, access files, run applications.

Think of it like AWS: the AWS Console (Hoody API) vs. your EC2 instance (container URLs).

Can I use the Hoody API without the Hoody Kit?

Section titled “Can I use the Hoody API without the Hoody Kit?”

Yes! When creating containers, set hoody_kit: false to get a plain Linux container without the 18 HTTP services. You’ll still use the Hoody API to manage it, but the container won’t have terminal/files/display HTTP endpoints—just SSH and any services you install yourself.

Do I need different auth tokens for different projects?

Section titled “Do I need different auth tokens for different projects?”

Not required, but recommended for blast-radius control. One token can cover multiple projects, while per-app/per-realm tokens are easier to audit and revoke.

How quickly can I spawn a container via the API?

Section titled “How quickly can I spawn a container via the API?”

Typically 20-30 seconds from API call to running container with all services live. Prespawn Templates can reduce this to under 5 seconds by maintaining pre-created container pools.

Can AI agents directly use the Hoody API?

Section titled “Can AI agents directly use the Hoody API?”

Absolutely. LLMs understand HTTP natively—they were trained on web data. An AI agent needs only a Hoody auth token (environment variable) and can immediately orchestrate your entire infrastructure through standard HTTP requests. No SDK required.

What happens if I delete a project via the API?

Section titled “What happens if I delete a project via the API?”

All containers in that project are immediately terminated and deleted. This is permanent and cannot be undone. Always snapshot important containers before deleting projects. The CLI and MCP surfaces gate this with an interactive confirmation prompt; if you’re calling the HTTP API directly, the call proceeds with no extra confirm parameter, so handle the prompt in your own tooling.

Can I automate infrastructure with GitHub Actions?

Section titled “Can I automate infrastructure with GitHub Actions?”

Yes! Store your Hoody auth token as a GitHub Secret (HOODY_TOKEN), then use curl or any HTTP library in your workflows to manage containers. Common pattern: Deploy on push by creating/updating containers via the API.

Is there a rate limit on the Hoody API?

Section titled “Is there a rate limit on the Hoody API?”

Current rate limits are generous and designed for automation. You can spawn dozens of containers per minute. If you hit rate limits, the API returns 429 Too Many Requests with retry timing. For enterprise-scale automation, contact support for increased limits.

Can I scope operations to specific realms?

Section titled “Can I scope operations to specific realms?”

Yes. Use realm-scoped API URLs: https://{realmId}.api.hoody.icu instead of https://api.hoody.icu.

Key rules:

  • {realmId} must be a 24-hex realm ID.
  • Realm-restricted tokens (realm_ids non-empty or allow_no_realm: false) must use realm-scoped URLs for resource operations.
  • GET /api/v1/auth/tokens/me is the bootstrap endpoint for discovering allowed realms.

What’s the maximum number of containers I can create?

Section titled “What’s the maximum number of containers I can create?”

There’s no hard platform limit. Practical limits: server resources (CPU/RAM) and organization (managing hundreds of containers becomes complex). Use projects to organize, and consider prespawn templates for container pooling at scale.

Troubleshooting

Section titled “Troubleshooting”

401 Unauthorized

Section titled “401 Unauthorized”

Problem: All API requests return 401 Unauthorized

Solutions:

  1. Check token is included:

    Terminal window
    # Ensure Authorization header is present
    curl -v "https://api.hoody.icu/api/v1/projects" \
      -H "Authorization: Bearer $HOODY_TOKEN"
    

    # Look for: > Authorization: Bearer hdy_...

  2. Verify token format:

    Terminal window
    # JWT tokens start with: eyJ...
    # Auth tokens start with: hdy_...
    echo $HOODY_TOKEN

  3. Check token expiration:

GET List auth tokens to check expires_at field
/api/v1/auth/tokens
Click "Run" to execute the request
  1. Re-authenticate:
POST Login again to get fresh JWT
/api/v1/users/auth/login
Click "Run" to execute the request

403 Forbidden (Auth Token IP Whitelist)

Section titled “403 Forbidden (Auth Token IP Whitelist)”

Problem: Auth Token returns 403 Forbidden

Cause: Your current IP is not in the token’s IP whitelist

Check your IP:

GET Get token details to check IP whitelist
/api/v1/auth/tokens/{token_id}
Click "Run" to execute the request

Compare ip_whitelist with your current IP (run curl https://ifconfig.me in terminal).

Solutions:

  1. Update whitelist to include your IP:
PUT Update token IP whitelist
/api/v1/auth/tokens/{token_id}
Click "Run" to execute the request
  1. Create new token without IP restrictions:
POST Create unrestricted token
/api/v1/auth/tokens
Click "Run" to execute the request

404 Not Found

Section titled “404 Not Found”

Problem: Resource not found errors

Common causes:

  1. Wrong ID format:

    Terminal window
    # IDs must be 24-character hex
    # ❌ Wrong: abc123
    # ✅ Correct: 507f1f77bcf86cd799439011

  2. Resource doesn’t exist:

    Terminal window
    # Verify resource exists
    GET /api/v1/projects          # List all projects
    GET /api/v1/containers        # List all containers

  3. Wrong endpoint path:

    /api/v1/project/507f1f77bcf86cd799439011
    # ✅ Correct: /api/v1/projects/507f1f77bcf86cd799439011

Network/Connection Errors

Section titled “Network/Connection Errors”

Problem: Can’t reach api.hoody.icu

Solutions:

  1. Check internet connection:

    Terminal window
    ping api.hoody.icu

  2. Verify DNS resolution:

    Terminal window
    dig api.hoody.icu
    # Should return IP address

  3. Test with curl verbose:

    Terminal window
    curl -v "https://api.hoody.icu/api/v1/projects" \
      -H "Authorization: Bearer $HOODY_TOKEN"
    

    # Look for TLS handshake and connection details

  4. Check firewall/proxy:

    • Corporate firewall might block HTTPS
    • VPN might interfere with connections
    • Try from different network

Rate Limiting

Section titled “Rate Limiting”

Problem: 429 Too Many Requests

Solution: Hoody API currently has generous rate limits. If you hit this:

  1. Add delays between requests:

    for (const item of items) {
      await fetch(apiUrl, options);
      await new Promise(r => setTimeout(r, 100)); // 100ms delay
    }

  2. Batch operations where possible:

    Terminal window
    # Instead of 10 separate container creates
    # Create them with delay or use prespawn pools

Getting Help

Section titled “Getting Help”

If issues persist:

  1. Review error message - Hoody returns detailed error messages in JSON
  2. Contact support with:
    • Request method and endpoint
    • Request headers (mask auth token)
    • Error response
    • Timestamp of failure

Next Steps

Section titled “Next Steps”

Understand the foundation:

  1. Authentication → - How to authenticate (JWTs vs Auth Tokens)
  2. Projects & Containers → - How Hoody organizes your infinite computers
  3. Hoody Proxy → - How every container feature becomes a URL

See complete endpoint documentation:

The Hoody API is your control plane.
Use it to spawn infinite computers.
Then use their URLs to actually work.

This is the foundation. Everything else builds on HTTP.