Projects

The Projects API lets you create and manage logical groupings for your containers, networks, and resources. Projects enforce optional container quotas, can be shared across realms, and support fine-grained per-user access control with read, edit, or delete permission levels. This page also documents the aggregated statistics endpoint for a project and the server rental runtime aliases that surface live host metrics.

All endpoints below use the Hoody control-plane host https://api.hoody.com. The TypeScript SDK is published as hoody-sdk.

Project Management

List Projects

GET /api/v1/projects/

List every project you own or have been granted access to. Supports pagination, sorting, and an optional realm filter.

cURL

curl -X GET "https://api.hoody.com/api/v1/projects/?page=1&limit=10&sort_by=created_at&sort_order=desc" \
  -H "Authorization: Bearer <token>"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.projects.listIterator({ page: 1, limit: 10, sort_by: 'created_at', sort_order: 'desc' });

Response 200

{
  "statusCode": 200,
  "message": "Projects retrieved successfully",
  "data": {
    "projects": [
      {
        "id": "507f1f77bcf86cd799439011",
        "user_id": "507f1f77bcf86cd799439022",
        "alias": "Production Environment",
        "color": "#3B82F6",
        "created_at": "2025-01-10T08:00:00.000Z",
        "updated_at": "2025-01-15T10:30:00.000Z",
        "max_containers": 50
      },
      {
        "id": "507f1f77bcf86cd799439033",
        "user_id": "507f1f77bcf86cd799439022",
        "alias": "Development",
        "color": "#10B981",
        "created_at": "2025-01-05T12:00:00.000Z",
        "updated_at": "2025-01-05T12:00:00.000Z",
        "max_containers": null
      }
    ],
    "pagination": {
      "total": 3,
      "page": 1,
      "limit": 10,
      "totalPages": 1
    }
  }
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid parameter value"
}

Error Code	Title	Description	Resolution
INVALID_PARAMETER_VALUE	Invalid parameter value	A parameter value is outside the allowed range or format	Ensure parameter values meet the documented constraints (min/max, format, regex)

401

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication token required"
}

Error Code	Title	Description	Resolution
MISSING_TOKEN	Authentication token missing	No authentication token was provided in the request	Include a valid JWT token in the Authorization header as Bearer <token>
INVALID_TOKEN	Invalid authentication token	The provided authentication token is malformed or invalid	Obtain a new token by logging in again or using a valid auth token
TOKEN_EXPIRED	Authentication token expired	The provided authentication token has expired	Obtain a new token by logging in again or refreshing your session

Parameters

Name	In	Type	Required	Description
page	query	number	No	Page number (1-based). Default: 1
limit	query	number	No	Items per page (max 100). Default: 10
sort_by	query	string	No	Field to sort by. Allowed values: id, alias, created_at, updated_at. Default: "created_at"
sort_order	query	string	No	Sort direction. Allowed values: asc, desc. Default: "desc"
realm_id	query	string	No	Filter by realm ID. Only returns projects that belong to this realm. Alternative to using the realm subdomain in the URL

Get Project by ID

GET /api/v1/projects/{id}

Retrieve a single project by ID. Pass include_permissions=true to also receive the list of users with access.

cURL

curl -X GET "https://api.hoody.com/api/v1/projects/507f1f77bcf86cd799439011?include_permissions=true" \
  -H "Authorization: Bearer <token>"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.projects.get('507f1f77bcf86cd799439011', { include_permissions: true });

Response 200

{
  "statusCode": 200,
  "message": "Project retrieved successfully",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "user_id": "507f1f77bcf86cd799439022",
    "alias": "Production Environment",
    "color": "#3B82F6",
    "created_at": "2025-01-10T08:00:00.000Z",
    "updated_at": "2025-01-15T10:30:00.000Z",
    "max_containers": 50,
    "permissions": [
      {
        "id": "507f1f77bcf86cd799439033",
        "project_id": "507f1f77bcf86cd799439011",
        "user_id": "507f1f77bcf86cd799439044",
        "permission_level": "read",
        "created_at": "2025-01-12T14:00:00.000Z",
        "updated_at": "2025-01-12T14:00:00.000Z",
        "user": {
          "id": "507f1f77bcf86cd799439044",
          "username": "jane_smith",
          "alias": "Jane Smith"
        }
      }
    ]
  }
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid ID format"
}

Error Code	Title	Description	Resolution
INVALID_ID_FORMAT	Invalid ID format	The provided ID must be a 24-character hexadecimal string	Ensure the ID is exactly 24 characters long and contains only hexadecimal characters (0-9, a-f)
INVALID_PARAMETER_VALUE	Invalid parameter value	A parameter value is outside the allowed range or format	Ensure parameter values meet the documented constraints (min/max, format, regex)

401

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication token required"
}

Error Code	Title	Description	Resolution
MISSING_TOKEN	Authentication token missing	No authentication token was provided in the request	Include a valid JWT token in the Authorization header as Bearer <token>
INVALID_TOKEN	Invalid authentication token	The provided authentication token is malformed or invalid	Obtain a new token by logging in again or using a valid auth token
TOKEN_EXPIRED	Authentication token expired	The provided authentication token has expired	Obtain a new token by logging in again or refreshing your session

403

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Insufficient permissions"
}

Error Code	Title	Description	Resolution
INSUFFICIENT_PERMISSIONS	Insufficient permissions	You do not have the required permissions to perform this action	Contact the resource owner or administrator to request access
ACCOUNT_BANNED	Account banned	Your account has been banned and cannot access this resource	Contact support for information about your account status

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Project not found"
}

Error Code	Title	Description	Resolution
PROJECT_NOT_FOUND	Project not found	The requested project does not exist or has been deleted	Verify the project ID is correct and that you have access to this project

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Project ID
include_permissions	query	boolean	No	Include project permissions with user details in the response. Default: false

Create Project

POST /api/v1/projects/

Create a new project to organize containers, networks, and resources. The alias must be unique across your projects.

cURL

curl -X POST "https://api.hoody.com/api/v1/projects/" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "alias": "Production Environment",
    "color": "#EF4444",
    "max_containers": 100
  }'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.projects.create({
  alias: 'Production Environment',
  color: '#EF4444',
  max_containers: 100,
});

Request Body

{
  "alias": "Production Environment",
  "color": "#EF4444",
  "max_containers": 100,
  "realm_ids": [
    "507f1f77bcf86cd799439011",
    "507f1f77bcf86cd799439022"
  ]
}

Field	Type	Required	Description
alias	string	Yes	Human-readable project name. Must be unique across your projects. 1-100 characters
color	string	No	HEX color code (3 or 6 digits). The # prefix is auto-added if missing and the value is auto-normalized to uppercase. If not provided, a random color is generated
max_containers	number | null	No	Maximum containers allowed in this project. null means unlimited. The quota is enforced during container creation
realm_ids	array	No	Realm IDs to assign this project to. If you create from a realm subdomain, that realm is automatically included and merged with any explicit values

Response 201

{
  "statusCode": 201,
  "message": "Project created successfully",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "user_id": "507f1f77bcf86cd799439022",
    "alias": "Production Environment",
    "color": "#3B82F6",
    "created_at": "2025-01-10T08:00:00.000Z",
    "updated_at": "2025-01-10T08:00:00.000Z",
    "max_containers": 50,
    "realm_ids": []
  }
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Validation failed"
}

Error Code	Title	Description	Resolution
VALIDATION_ERROR	Invalid input parameters	One or more request parameters failed validation	Check the error message for specific field requirements and correct your input
MISSING_REQUIRED_FIELD	Required field missing	One or more required fields are missing from the request	Include all required fields as specified in the API documentation
INVALID_ALIAS_FORMAT	Invalid alias format	Project alias must be between 1-100 characters	Provide a valid alias following the format requirements: 1-100 characters
INVALID_COLOR_FORMAT	Invalid color format	Color must be a valid HEX color code (3 or 6 digits)	Provide a valid HEX color like #RGB or #RRGGBB (for example, #F00 or #FF0000)
INVALID_QUOTA_VALUE	Invalid quota value	Quota values must be non-negative numbers or null	Provide a valid quota value (0 or higher) or null for unlimited

401

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication token required"
}

Error Code	Title	Description	Resolution
MISSING_TOKEN	Authentication token missing	No authentication token was provided in the request	Include a valid JWT token in the Authorization header as Bearer <token>
INVALID_TOKEN	Invalid authentication token	The provided authentication token is malformed or invalid	Obtain a new token by logging in again or using a valid auth token
TOKEN_EXPIRED	Authentication token expired	The provided authentication token has expired	Obtain a new token by logging in again or refreshing your session

409

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Project alias already exists"
}

Error Code	Title	Description	Resolution
DUPLICATE_ALIAS	Project alias already exists	The provided project alias is already in use by another project in your account	Choose a different, unique project alias

This endpoint takes no path, query, or header parameters.

Update Project

PUT /api/v1/projects/{id}

Update an existing project. You must be the owner or hold edit permission. The alias field is required in the body; other fields are only updated when supplied.

cURL

curl -X PUT "https://api.hoody.com/api/v1/projects/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "alias": "Production v2",
    "color": "#10B981",
    "max_containers": 75
  }'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.projects.update('507f1f77bcf86cd799439011', {
  alias: 'Production v2',
  color: '#10B981',
  max_containers: 75,
});

Request Body

{
  "alias": "Production v2",
  "color": "#10B981",
  "max_containers": 75,
  "realm_ids": [
    "507f1f77bcf86cd799439011"
  ]
}

Field	Type	Required	Description
alias	string	Yes	New project name. Must be unique across your projects. 1-100 characters
color	string	No	New HEX color code. Auto-normalized to uppercase with the # prefix
max_containers	number | null	No	Maximum containers allowed in this project. null means unlimited. The quota is enforced during container creation
realm_ids	array	No	Update realm membership. Only unrestricted tokens and admin users can modify realm_ids; realm-restricted tokens cannot change realm membership

Response 200

{
  "statusCode": 200,
  "message": "Project updated successfully",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "user_id": "507f1f77bcf86cd799439022",
    "alias": "Production Environment Updated",
    "color": "#EF4444",
    "created_at": "2025-01-10T08:00:00.000Z",
    "updated_at": "2025-01-15T14:45:00.000Z",
    "max_containers": 50
  }
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Validation failed"
}

Error Code	Title	Description	Resolution
VALIDATION_ERROR	Invalid input parameters	One or more request parameters failed validation	Check the error message for specific field requirements and correct your input
INVALID_ID_FORMAT	Invalid ID format	The provided ID must be a 24-character hexadecimal string	Ensure the ID is exactly 24 characters long and contains only hexadecimal characters (0-9, a-f)
INVALID_ALIAS_FORMAT	Invalid alias format	Project alias must be between 1-100 characters	Provide a valid alias following the format requirements: 1-100 characters
INVALID_COLOR_FORMAT	Invalid color format	Color must be a valid HEX color code (3 or 6 digits)	Provide a valid HEX color like #RGB or #RRGGBB (for example, #F00 or #FF0000)
INVALID_QUOTA_VALUE	Invalid quota value	Quota values must be non-negative numbers or null	Provide a valid quota value (0 or higher) or null for unlimited

401

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication token required"
}

Error Code	Title	Description	Resolution
MISSING_TOKEN	Authentication token missing	No authentication token was provided in the request	Include a valid JWT token in the Authorization header as Bearer <token>
INVALID_TOKEN	Invalid authentication token	The provided authentication token is malformed or invalid	Obtain a new token by logging in again or using a valid auth token
TOKEN_EXPIRED	Authentication token expired	The provided authentication token has expired	Obtain a new token by logging in again or refreshing your session

403

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Insufficient permissions"
}

Error Code	Title	Description	Resolution
INSUFFICIENT_PERMISSIONS	Insufficient permissions	You do not have the required permissions to perform this action	Contact the resource owner or administrator to request access
ACCOUNT_BANNED	Account banned	Your account has been banned and cannot access this resource	Contact support for information about your account status

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Project not found"
}

Error Code	Title	Description	Resolution
PROJECT_NOT_FOUND	Project not found	The requested project does not exist or has been deleted	Verify the project ID is correct and that you have access to this project

409

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Project alias already exists"
}

Error Code	Title	Description	Resolution
DUPLICATE_ALIAS	Project alias already exists	The provided project alias is already in use by another project in your account	Choose a different, unique project alias

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Project ID to update

Delete Project

DELETE /api/v1/projects/{id}

Permanently delete a project and tear down its associated resources. If deletion cannot be fully completed, the project remains available so you can retry safely. You must be the owner or hold delete permission.

Danger

This action cannot be undone. Delete every container inside the project first, or the API rejects the request with PROJECT_HAS_CONTAINERS.

cURL

curl -X DELETE "https://api.hoody.com/api/v1/projects/507f1f77bcf86cd799439011?include_deleted_items=true" \
  -H "Authorization: Bearer <token>"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.projects.delete('507f1f77bcf86cd799439011', { include_deleted_items: true });

Response 200

{
  "statusCode": 200,
  "message": "Project deleted successfully",
  "data": {
    "deleted": {
      "containers": 2,
      "permissions": 1,
      "aliases": 3
    },
    "deleted_items": {
      "containers": [
        {
          "id": "507f1f77bcf86cd799439011",
          "name": "web-app"
        },
        {
          "id": "507f1f77bcf86cd799439012",
          "name": "worker"
        }
      ]
    }
  }
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid ID format"
}

Error Code	Title	Description	Resolution
INVALID_ID_FORMAT	Invalid ID format	The provided ID must be a 24-character hexadecimal string	Ensure the ID is exactly 24 characters long and contains only hexadecimal characters (0-9, a-f)

401

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication token required"
}

Error Code	Title	Description	Resolution
MISSING_TOKEN	Authentication token missing	No authentication token was provided in the request	Include a valid JWT token in the Authorization header as Bearer <token>
INVALID_TOKEN	Invalid authentication token	The provided authentication token is malformed or invalid	Obtain a new token by logging in again or using a valid auth token
TOKEN_EXPIRED	Authentication token expired	The provided authentication token has expired	Obtain a new token by logging in again or refreshing your session

403

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Insufficient permissions"
}

Error Code	Title	Description	Resolution
INSUFFICIENT_PERMISSIONS	Insufficient permissions	You do not have the required permissions to perform this action	Contact the resource owner or administrator to request access
ACCOUNT_BANNED	Account banned	Your account has been banned and cannot access this resource	Contact support for information about your account status

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Project not found"
}

Error Code	Title	Description	Resolution
PROJECT_NOT_FOUND	Project not found	The requested project does not exist or has been deleted	Verify the project ID is correct and that you have access to this project

409

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Resource already exists"
}

Error Code	Title	Description	Resolution
RESOURCE_ALREADY_EXISTS	Resource already exists	A resource with this identifier already exists	Use a different identifier or update the existing resource instead

422

{
  "statusCode": 422,
  "error": "Unprocessable Entity",
  "message": "Project contains active containers"
}

Error Code	Title	Description	Resolution
PROJECT_HAS_CONTAINERS	Project has active containers	Cannot delete project because it contains active containers	Delete all containers in this project first, then try again

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Project ID to delete
include_deleted_items	query	boolean	No	Include a lightweight list of deleted container IDs and names in the response for confirmation UX. Default: false

Project Permissions

List Project Permissions

GET /api/v1/projects/{id}/permissions

List every user who has been granted access to a project, including their permission level. Supports pagination and sorting.

cURL

curl -X GET "https://api.hoody.com/api/v1/projects/507f1f77bcf86cd799439011/permissions?page=1&limit=10&sort_by=user_id&sort_order=asc" \
  -H "Authorization: Bearer <token>"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.projects.listPermissionsIterator('507f1f77bcf86cd799439011', { page: 1, limit: 10, sort_by: 'user_id', sort_order: 'asc' });

Response 200

{
  "statusCode": 200,
  "message": "Project permissions retrieved successfully",
  "data": {
    "permissions": [
      {
        "id": "507f1f77bcf86cd799439033",
        "project_id": "507f1f77bcf86cd799439011",
        "user_id": "507f1f77bcf86cd799439044",
        "permission_level": "read",
        "created_at": "2025-01-12T14:00:00.000Z",
        "updated_at": "2025-01-12T14:00:00.000Z",
        "user": {
          "id": "507f1f77bcf86cd799439044",
          "username": "jane_smith",
          "alias": "Jane Smith"
        }
      },
      {
        "id": "507f1f77bcf86cd799439055",
        "project_id": "507f1f77bcf86cd799439011",
        "user_id": "507f1f77bcf86cd799439066",
        "permission_level": "edit",
        "created_at": "2025-01-13T09:30:00.000Z",
        "updated_at": "2025-01-14T16:20:00.000Z",
        "user": {
          "id": "507f1f77bcf86cd799439066",
          "username": "bob_jones",
          "alias": "Bob Jones"
        }
      }
    ],
    "pagination": {
      "total": 2,
      "page": 1,
      "limit": 10,
      "totalPages": 1
    }
  }
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid request"
}

401

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication token required"
}

403

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Insufficient permissions"
}

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Project not found"
}

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Project ID
page	query	number	No	Page number (1-based)
limit	query	number	No	Items per page (max 100)
sort_by	query	string	No	Field to sort by. Allowed values: id, user_id, permission_level, created_at, updated_at
sort_order	query	string	No	Sort direction. Allowed values: asc, desc

Grant Project Access

POST /api/v1/projects/{id}/permissions

Grant another user access to your project. You must be the owner or hold edit permission. Use read for view-only access, edit to allow modifications, or delete to allow destroying the project.

cURL

curl -X POST "https://api.hoody.com/api/v1/projects/507f1f77bcf86cd799439011/permissions" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "507f1f77bcf86cd799439044",
    "permission_level": "edit"
  }'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.projects.addPermission('507f1f77bcf86cd799439011', {
  user_id: '507f1f77bcf86cd799439044',
  permission_level: 'edit',
});

Request Body

{
  "user_id": "507f1f77bcf86cd799439044",
  "permission_level": "edit"
}

Field	Type	Required	Description
user_id	string	Yes	User ID to grant access to
permission_level	string	Yes	Access level. Allowed values: read, edit, delete

Response 201

{
  "statusCode": 201,
  "message": "Project permission added successfully",
  "data": {
    "id": "507f1f77bcf86cd799439033",
    "project_id": "507f1f77bcf86cd799439011",
    "user_id": "507f1f77bcf86cd799439044",
    "permission_level": "read",
    "created_at": "2025-01-12T14:00:00.000Z",
    "updated_at": "2025-01-12T14:00:00.000Z",
    "user": {
      "id": "507f1f77bcf86cd799439044",
      "username": "jane_smith",
      "alias": "Jane Smith"
    }
  }
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Validation failed"
}

Error Code	Title	Description	Resolution
VALIDATION_ERROR	Invalid input parameters	One or more request parameters failed validation	Check the error message for specific field requirements and correct your input
INVALID_ID_FORMAT	Invalid ID format	The provided ID must be a 24-character hexadecimal string	Ensure the ID is exactly 24 characters long and contains only hexadecimal characters (0-9, a-f)
MISSING_REQUIRED_FIELD	Required field missing	One or more required fields are missing from the request	Include all required fields as specified in the API documentation

401

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication token required"
}

Error Code	Title	Description	Resolution
MISSING_TOKEN	Authentication token missing	No authentication token was provided in the request	Include a valid JWT token in the Authorization header as Bearer <token>
INVALID_TOKEN	Invalid authentication token	The provided authentication token is malformed or invalid	Obtain a new token by logging in again or using a valid auth token
TOKEN_EXPIRED	Authentication token expired	The provided authentication token has expired	Obtain a new token by logging in again or refreshing your session

403

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Insufficient permissions"
}

Error Code	Title	Description	Resolution
INSUFFICIENT_PERMISSIONS	Insufficient permissions	You do not have the required permissions to perform this action	Contact the resource owner or administrator to request access
ACCOUNT_BANNED	Account banned	Your account has been banned and cannot access this resource	Contact support for information about your account status

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Project not found"
}

Error Code	Title	Description	Resolution
PROJECT_NOT_FOUND	Project not found	The requested project does not exist or has been deleted	Verify the project ID is correct and that you have access to this project
RESOURCE_NOT_FOUND	Resource not found	The requested resource does not exist or has been deleted	Verify the resource ID and ensure it exists

409

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "User already has permission for this project"
}

Error Code	Title	Description	Resolution
PERMISSION_ALREADY_EXISTS	Permission already exists	This user already has a permission for this project	Update the existing permission instead of creating a new one
CANNOT_GRANT_SELF_PERMISSION	Cannot grant permission to self	You cannot grant permissions to yourself	As the owner, you already have full access to this project

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Project ID

Update Project Permission

PUT /api/v1/projects/{id}/permissions/{permissionId}

Change an existing permission level for a user. Use this to upgrade from read to edit, downgrade from edit to read, or grant delete rights. You must be the owner or hold edit permission.

cURL

curl -X PUT "https://api.hoody.com/api/v1/projects/507f1f77bcf86cd799439011/permissions/507f1f77bcf86cd799439033" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "permission_level": "edit" }'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.projects.updatePermission('507f1f77bcf86cd799439011', '507f1f77bcf86cd799439033', {
  permission_level: 'edit',
});

Request Body

{
  "permission_level": "edit"
}

Field	Type	Required	Description
permission_level	string	Yes	New permission level. Allowed values: read, edit, delete

Response 200

{
  "statusCode": 200,
  "message": "Project permission updated successfully",
  "data": {
    "id": "507f1f77bcf86cd799439033",
    "project_id": "507f1f77bcf86cd799439011",
    "user_id": "507f1f77bcf86cd799439044",
    "permission_level": "edit",
    "created_at": "2025-01-12T14:00:00.000Z",
    "updated_at": "2025-01-15T14:45:00.000Z",
    "user": {
      "id": "507f1f77bcf86cd799439044",
      "username": "jane_smith",
      "alias": "Jane Smith"
    }
  }
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Validation failed"
}

Error Code	Title	Description	Resolution
VALIDATION_ERROR	Invalid input parameters	One or more request parameters failed validation	Check the error message for specific field requirements and correct your input
INVALID_ID_FORMAT	Invalid ID format	The provided ID must be a 24-character hexadecimal string	Ensure the ID is exactly 24 characters long and contains only hexadecimal characters (0-9, a-f)
MISSING_REQUIRED_FIELD	Required field missing	One or more required fields are missing from the request	Include all required fields as specified in the API documentation

401

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication token required"
}

Error Code	Title	Description	Resolution
MISSING_TOKEN	Authentication token missing	No authentication token was provided in the request	Include a valid JWT token in the Authorization header as Bearer <token>
INVALID_TOKEN	Invalid authentication token	The provided authentication token is malformed or invalid	Obtain a new token by logging in again or using a valid auth token
TOKEN_EXPIRED	Authentication token expired	The provided authentication token has expired	Obtain a new token by logging in again or refreshing your session

403

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Insufficient permissions"
}

Error Code	Title	Description	Resolution
INSUFFICIENT_PERMISSIONS	Insufficient permissions	You do not have the required permissions to perform this action	Contact the resource owner or administrator to request access
ACCOUNT_BANNED	Account banned	Your account has been banned and cannot access this resource	Contact support for information about your account status

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Project not found"
}

Error Code	Title	Description	Resolution
PROJECT_NOT_FOUND	Project not found	The requested project does not exist or has been deleted	Verify the project ID is correct and that you have access to this project
PERMISSION_NOT_FOUND	Permission not found	The requested permission does not exist or has been removed	Verify the permission ID is correct

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Project ID
permissionId	path	string	Yes	Permission ID to update

Revoke Project Access

DELETE /api/v1/projects/{id}/permissions/{permissionId}

Revoke a user’s access to a project. The user immediately loses all access. You must be the owner or hold edit permission.

cURL

curl -X DELETE "https://api.hoody.com/api/v1/projects/507f1f77bcf86cd799439011/permissions/507f1f77bcf86cd799439033" \
  -H "Authorization: Bearer <token>"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.projects.removePermission('507f1f77bcf86cd799439011', '507f1f77bcf86cd799439033');

Response 200

{
  "statusCode": 200,
  "message": "Project permission removed successfully"
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid request"
}

401

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication token required"
}

403

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Insufficient permissions"
}

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Project not found"
}

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Project ID
permissionId	path	string	Yes	Permission ID to remove

Project Statistics

Get Project Statistics

GET /api/v1/projects/{id}/stats

Aggregate resource usage statistics for every container in a project. Returns per-container CPU, memory, ramdisk, disk, and network counters, plus a summary block with container count and total processing time.

cURL

curl -X GET "https://api.hoody.com/api/v1/projects/507f1f77bcf86cd799439011/stats" \
  -H "Authorization: Bearer <token>"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.projects.getStats('507f1f77bcf86cd799439011');

Response 200

{
  "statusCode": 200,
  "message": "Project statistics retrieved successfully",
  "data": {
    "stats": [
      {
        "id": "507f1f77bcf86cd799439011",
        "project_id": "507f1f77bcf86cd799439033",
        "project_name": "Production Environment",
        "server_name": "node-sg-sin-1",
        "status": "Running",
        "status_code": 103,
        "processes": 143,
        "started_at": "2025-12-03T18:39:53Z",
        "cpu": {
          "usage": 17303605000
        },
        "memory": {
          "usage": 1474666496,
          "total": 131503332000
        },
        "disk": {
          "root": {
            "total": 0,
            "usage": 11081670656
          }
        },
        "network": [],
        "processing_time": "3ms"
      }
    ],
    "summary": {
      "project_id": "507f1f77bcf86cd799439033",
      "project_name": "Production Environment",
      "container_count": 29,
      "total_processing_time": "1506ms"
    }
  }
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid ID format"
}

Error Code	Title	Description	Resolution
INVALID_ID_FORMAT	Invalid ID format	The provided ID must be a 24-character hexadecimal string	Ensure the ID is exactly 24 characters long and contains only hexadecimal characters (0-9, a-f)

401

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication token required"
}

Error Code	Title	Description	Resolution
MISSING_TOKEN	Authentication token missing	No authentication token was provided in the request	Include a valid JWT token in the Authorization header as Bearer <token>
INVALID_TOKEN	Invalid authentication token	The provided authentication token is malformed or invalid	Obtain a new token by logging in again or using a valid auth token
TOKEN_EXPIRED	Authentication token expired	The provided authentication token has expired	Obtain a new token by logging in again or refreshing your session

403

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Insufficient permissions"
}

Error Code	Title	Description	Resolution
INSUFFICIENT_PERMISSIONS	Insufficient permissions	You do not have the required permissions to perform this action	Contact the resource owner or administrator to request access
ACCOUNT_BANNED	Account banned	Your account has been banned and cannot access this resource	Contact support for information about your account status
RESOURCE_ACCESS_DENIED	Resource access denied	You do not have permission to access this specific resource	Ensure you own this resource or have been granted access by the owner

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Resource not found"
}

Error Code	Title	Description	Resolution
RESOURCE_NOT_FOUND	Resource not found	The requested resource does not exist or has been deleted	Verify the resource ID and ensure it exists

500

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "An unexpected error occurred"
}

Error Code	Title	Description	Resolution
INTERNAL_SERVER_ERROR	Internal server error	An unexpected error occurred on the server	Try again later, or contact support if the problem persists
EXTERNAL_SERVICE_ERROR	External service error	A required external service is unavailable or returned an error	Try again later when the external service is available

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Unique identifier of the project

Server Rental Runtime

The endpoints in this section expose live CPU, memory, and disk counters for rented physical servers and their subserver slices. Data is served from a short-TTL cache so it can be polled frequently. First-party JWT is required. GET /api/v1/servers/{id}/runtime is an alias for GET /api/v1/rentals/{id}/runtime.

Note

Physical host runtime is only returned when the server hosts no subservers and is not a shared system host. For physical servers that do host subservers, the API returns 409 RUNTIME_HOST_SHARED because exposing those counters would leak co-tenant activity. Query the subserver instead.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	id path parameter

Get Rental Runtime

GET /api/v1/rentals/{id}/runtime

cURL

curl -X GET "https://api.hoody.com/api/v1/rentals/507f1f77bcf86cd799439077/runtime" \
  -H "Authorization: Bearer <token>"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.serverRental.getRentalRuntime('507f1f77bcf86cd799439077');

Response 200

{
  "statusCode": 200,
  "message": "Runtime info retrieved successfully",
  "data": {
    "scope": "server",
    "ts": "2025-12-03T18:39:53.000Z",
    "cache_age_ms": 1200,
    "stale": false,
    "uptime_s": 86400,
    "cores": 64,
    "load": { "1": 0.42, "5": 0.51, "15": 0.47 },
    "cpu": { "busy_pct": 12.4 },
    "mem": { "used_bytes": 8589934592, "total_bytes": 137438953472, "pct": 6.25 },
    "swap": { "used_bytes": 0, "total_bytes": 0 },
    "storage": { "used_bytes": 524288000000, "total_bytes": 1999844147200, "pct": 26.21 }
  }
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid ID format"
}

Error Code	Title	Description	Resolution
INVALID_ID_FORMAT	Invalid ID format	The provided ID must be a 24-character hexadecimal string	Ensure the ID is exactly 24 characters long and contains only hexadecimal characters (0-9, a-f)

401

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication token required"
}

Error Code	Title	Description	Resolution
MISSING_TOKEN	Authentication token missing	No authentication token was provided in the request	Include a valid JWT token in the Authorization header as Bearer <token>
INVALID_TOKEN	Invalid authentication token	The provided authentication token is malformed or invalid	Obtain a new token by logging in again or using a valid auth token

403

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Insufficient permissions"
}

Error Code	Title	Description	Resolution
INSUFFICIENT_PERMISSIONS	Insufficient permissions	You do not have the required permissions to perform this action	Contact the resource owner or administrator to request access

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Resource not found"
}

Error Code	Title	Description	Resolution
RESOURCE_NOT_FOUND	Resource not found	The requested resource does not exist or has been deleted	Verify the resource ID and ensure it exists

409

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Host runtime not available for a shared server"
}

Error Code	Title	Description	Resolution
RUNTIME_HOST_SHARED	Host runtime not available for a shared server	Host-level runtime info is not exposed for a physical server that hosts subservers or is a system server, because it would reveal co-tenant activity	Query runtime for the specific subserver you rent instead of the whole physical host

429

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded"
}

Error Code	Title	Description	Resolution
RATE_LIMIT_EXCEEDED	Rate limit exceeded	You have exceeded the rate limit for this endpoint	Wait before making additional requests, or upgrade your plan for higher limits

503

{
  "statusCode": 503,
  "error": "Service Unavailable",
  "message": "Runtime info temporarily unavailable"
}

Error Code	Title	Description	Resolution
RUNTIME_UNAVAILABLE	Runtime info temporarily unavailable	Live runtime info could not be collected for this server and no recent snapshot is available	Retry shortly. If it persists, the host may be unreachable or under maintenance

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Rental or server ID

Get Server Runtime

GET /api/v1/servers/{id}/runtime

Alias for GET /api/v1/rentals/{id}/runtime. Returns the same payload, statuses, and error codes.

cURL

curl -X GET "https://api.hoody.com/api/v1/servers/507f1f77bcf86cd799439077/runtime" \
  -H "Authorization: Bearer <token>"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.serverRental.getServerRuntime('507f1f77bcf86cd799439077');

Response 200

{
  "statusCode": 200,
  "message": "Runtime info retrieved successfully",
  "data": {
    "scope": "subserver",
    "ts": "2025-12-03T18:39:53.000Z",
    "cache_age_ms": 850,
    "stale": false,
    "health": "ok",
    "cpu": { "usage_cores": 1.2, "usage_pct": 9.6, "limit_cores": 12.5 },
    "mem": { "used_bytes": 4294967296, "limit_bytes": 34359738368, "pct": 12.5 },
    "disk": { "used_bytes": 21474836480, "limit_bytes": 536870912000, "pct": 4.0 },
    "pids": { "current": 184, "max": 4096 },
    "io": { "read_bytes": 104857600, "write_bytes": 52428800 }
  }
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid ID format"
}

Error Code	Title	Description	Resolution
INVALID_ID_FORMAT	Invalid ID format	The provided ID must be a 24-character hexadecimal string	Ensure the ID is exactly 24 characters long and contains only hexadecimal characters (0-9, a-f)

401

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication token required"
}

Error Code	Title	Description	Resolution
MISSING_TOKEN	Authentication token missing	No authentication token was provided in the request	Include a valid JWT token in the Authorization header as Bearer <token>
INVALID_TOKEN	Invalid authentication token	The provided authentication token is malformed or invalid	Obtain a new token by logging in again or using a valid auth token

403

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Insufficient permissions"
}

Error Code	Title	Description	Resolution
INSUFFICIENT_PERMISSIONS	Insufficient permissions	You do not have the required permissions to perform this action	Contact the resource owner or administrator to request access

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Resource not found"
}

Error Code	Title	Description	Resolution
RESOURCE_NOT_FOUND	Resource not found	The requested resource does not exist or has been deleted	Verify the resource ID and ensure it exists

409

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Host runtime not available for a shared server"
}

Error Code	Title	Description	Resolution
RUNTIME_HOST_SHARED	Host runtime not available for a shared server	Host-level runtime info is not exposed for a physical server that hosts subservers or is a system server, because it would reveal co-tenant activity	Query runtime for the specific subserver you rent instead of the whole physical host

429

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded"
}

Error Code	Title	Description	Resolution
RATE_LIMIT_EXCEEDED	Rate limit exceeded	You have exceeded the rate limit for this endpoint	Wait before making additional requests, or upgrade your plan for higher limits

503

{
  "statusCode": 503,
  "error": "Service Unavailable",
  "message": "Runtime info temporarily unavailable"
}

Error Code	Title	Description	Resolution
RUNTIME_UNAVAILABLE	Runtime info temporarily unavailable	Live runtime info could not be collected for this server and no recent snapshot is available	Retry shortly. If it persists, the host may be unreachable or under maintenance

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Server ID