The user profile management endpoints let you retrieve and update user accounts, audit activity logs, and manage a personal encrypted key-value vault. Use these endpoints to manage account state, inspect API usage history, and store arbitrary secrets scoped to a user or realm.

User profile

GET /api/v1/users/{id}

Retrieve a user profile by ID. Admins can view any user; regular users can only view their own profile. This endpoint works even for banned users (read-only access).

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	User ID to retrieve

cURL

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

SDK

const { data, error } = await client.api.users.get({
  id: "507f1f77bcf86cd799439011",
});

Response 200

{
  "statusCode": 200,
  "message": "User retrieved successfully",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "username": "john_doe",
    "alias": "John Doe",
    "email": "john.doe@example.com",
    "is_admin": false,
    "is_banned": false,
    "metadata": {},
    "created_at": "2024-12-01T10:00:00.000Z",
    "updated_at": "2025-01-15T10:30:00.000Z"
  }
}

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": "User not found"
}

Error Code	Title	Description	Resolution
USER_NOT_FOUND	User not found	The requested user does not exist or has been deleted	Verify the user ID is correct

PATCH /api/v1/users/{id}

Update a user profile. Regular users can update their own alias and password (requires current_password verification). Admins can update any user and set is_admin/is_banned flags. Admin users cannot be banned.

Parameters

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

Request Body

Field	Type	Required	Description
alias	string	No	New display name/alias (1–100 characters)
public_key	string	No	ED25519 public key (exactly 64 hexadecimal characters)
metadata	object	No	Custom metadata object for additional user information
password	string	No	New password (≥12 characters, 3 of 4 character classes). Requires current_password.
current_password	string	No	Current password (8–128 characters). Required when setting a new password.
is_admin	boolean	No	Admin status. Admin-only field.
is_banned	boolean	No	Ban status. Admin-only field. Admin users cannot be banned.

cURL

curl -X PATCH "https://api.hoody.com/api/v1/users/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "alias": "John Smith",
    "public_key": "a1b2c3d4e5f6789012345678901234567890abcdefabcdefabcdefabcdef1234"
  }'

SDK

const { data, error } = await client.api.users.update({
  id: "507f1f77bcf86cd799439011",
  data: {
    alias: "John Smith",
    public_key: "a1b2c3d4e5f6789012345678901234567890abcdefabcdefabcdefabcdef1234",
  },
});

Response 200

{
  "statusCode": 200,
  "message": "User updated successfully",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "username": "john_doe",
    "alias": "John Smith",
    "email": "john.doe@example.com",
    "public_key": "a1b2c3d4e5f6789012345678901234567890abcdefabcdefabcdefabcdef1234",
    "is_admin": false,
    "is_banned": false,
    "metadata": {},
    "created_at": "2024-12-01T10:00:00.000Z",
    "updated_at": "2025-01-15T14:45:00.000Z"
  }
}

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_PUBLIC_KEY_FORMAT	Invalid public key format	Public key must be exactly 64 hexadecimal characters (ED25519 format)	Provide a valid ED25519 public key as a 64-character hexadecimal string
WEAK_PASSWORD	Password does not meet requirements	Password must be at least 12 characters, 3 of 4 character classes	Choose a password with at least 12 characters, 3 of 4 character classes
CURRENT_PASSWORD_REQUIRED	Current password required	You must provide your current password to set a new password	Include the current_password field in your request
CURRENT_PASSWORD_INCORRECT	Current password incorrect	The provided current password does not match your account password	Verify your current password and try again

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
CANNOT_BAN_ADMIN	Cannot ban admin users	Admin users cannot be banned for security reasons	Remove admin privileges before banning this user
CANNOT_MODIFY_OTHER_USER	Cannot modify other user	Regular users can only modify their own profile	You can only update your own profile, or request admin access

404

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

Error Code	Title	Description	Resolution
USER_NOT_FOUND	User not found	The requested user does not exist or has been deleted	Verify the user ID is correct

POST /api/v1/users/me/retry-setup

Manually claim a free-tier server and create the default project and container. This operation is idempotent and safe to call if the account is already provisioned.

Request Body

Field	Type	Required	Description
region	string	No	Optional preferred region override (lowercase alphanumeric and hyphens, max 50 characters)

cURL

curl -X POST "https://api.hoody.com/api/v1/users/me/retry-setup" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "region": "us-east-1"
  }'

SDK

const { data, error } = await client.api.users.retrySetup({
  data: {
    region: "us-east-1",
  },
});

Response 200

{
  "statusCode": 200,
  "data": {
    "server": {},
    "project": {},
    "container": {}
  }
}

Activity logs

GET /api/v1/users/auth/activity

Retrieve activity logs for the authenticated user with optional filtering by date range, status code, HTTP method, or realm.

Parameters

Name	In	Type	Required	Description
page	query	integer	No	Page number. Default: 1
limit	query	integer	No	Results per page. Default: 50
start_date	query	string	No	Filter logs after this date
end_date	query	string	No	Filter logs before this date
errors_only	query	string	No	Show only errors (status ≥ 400). Allowed values: "true", "false"
min_status	query	integer	No	Minimum status code
max_status	query	integer	No	Maximum status code
method	query	string	No	Filter by HTTP method. Allowed values: "GET", "POST", "PUT", "PATCH", "DELETE"
realm_id	query	string	No	Filter by realm ID

cURL

curl -X GET "https://api.hoody.com/api/v1/users/auth/activity?page=1&limit=50&errors_only=true" \
  -H "Authorization: Bearer <token>"

SDK

const { data, error } = await client.api.activity.listIterator({
  page: 1,
  limit: 50,
  errors_only: "true",
});

Response 200

{
  "statusCode": 200,
  "message": "Activity logs retrieved successfully",
  "data": [
    {
      "id": "1a9c3592695c087a8f35ceae",
      "user_id": "507f1f77bcf86cd799439011",
      "realm_id": "507f1f77bcf86cd799439011",
      "method": "GET",
      "path": "/api/v1/projects",
      "status_code": 200,
      "ip_address": "192.168.1.1",
      "user_agent": "Mozilla/5.0...",
      "created_at": "2025-11-18T20:00:00Z"
    }
  ],
  "metadata": {
    "total": 100,
    "page": 1,
    "limit": 50,
    "pages": 2
  }
}

GET /api/v1/users/auth/activity/stats

Retrieve storage usage statistics for activity logs, including total size, record counts, oldest and newest records, and retention window.

This endpoint takes no parameters.

cURL

curl -X GET "https://api.hoody.com/api/v1/users/auth/activity/stats" \
  -H "Authorization: Bearer <token>"

SDK

const { data, error } = await client.api.activity.getStats();

Response 200

{
  "statusCode": 200,
  "message": "Activity stats retrieved successfully",
  "data": {
    "total_size_bytes": 1048576,
    "total_records": 5000,
    "oldest_record": "2025-10-18T20:00:00Z",
    "newest_record": "2025-11-18T20:00:00Z",
    "retention_days": 30
  }
}

User vault

The user vault is a personal, per-realm key-value store. Values are opaque UTF-8 strings — the API does not validate or decrypt content, so client-side encryption is recommended for sensitive material.

GET /api/v1/vault/keys

List all keys in the encrypted vault with metadata. Values are not included — use GET /api/v1/vault/keys/{key} to retrieve a specific value.

Parameters

Name	In	Type	Required	Description
realm_id	query	string	No	Target a specific realm (24-char hex). When omitted and not on a realm subdomain, defaults to global scope (realm_id = ""). Case-insensitive — uppercase is normalized to lowercase.

cURL

curl -X GET "https://api.hoody.com/api/v1/vault/keys" \
  -H "Authorization: Bearer <token>"

SDK

const { data, error } = await client.api.vault.listIterator();

Response 200

{
  "statusCode": 200,
  "message": "Vault keys retrieved successfully",
  "data": [
    {
      "key": "my-encrypted-notes",
      "realm_id": "507f1f77bcf86cd799439011",
      "metadata": {},
      "size_bytes": 2048,
      "created_at": "2025-11-14T18:00:00.000Z",
      "updated_at": "2025-11-14T18:15:00.000Z"
    },
    {
      "key": "config.json",
      "realm_id": "",
      "metadata": null,
      "size_bytes": 512,
      "created_at": "2025-11-14T17:30:00.000Z",
      "updated_at": "2025-11-14T17:30:00.000Z"
    }
  ]
}

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

GET /api/v1/vault/keys/{key}

Retrieve a specific key-value pair from the encrypted vault by key name.

Parameters

Name	In	Type	Required	Description
realm_id	query	string	No	Target a specific realm (24-char hex). When omitted and not on a realm subdomain, defaults to global scope (realm_id = ""). Case-insensitive — uppercase is normalized to lowercase.
key	path	string	Yes	Vault key name (alphanumeric, dots, underscores, hyphens)

cURL

curl -X GET "https://api.hoody.com/api/v1/vault/keys/my-encrypted-notes" \
  -H "Authorization: Bearer <token>"

SDK

const { data, error } = await client.api.vault.get({
  key: "my-encrypted-notes",
});

Response 200

{
  "statusCode": 200,
  "message": "Vault key retrieved successfully",
  "data": {
    "key": "my-encrypted-notes",
    "realm_id": "507f1f77bcf86cd799439011",
    "value": "{\"notes\": \"My important notes\", \"encrypted\": true}",
    "metadata": {},
    "size_bytes": 53,
    "created_at": "2025-11-14T18:00:00.000Z",
    "updated_at": "2025-11-14T18:15:00.000Z"
  }
}

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": "Vault key not found."
}

Error Code	Title	Description	Resolution
VAULT_KEY_NOT_FOUND	Vault Key Not Found	The specified key does not exist in your vault.	Verify the key name is correct.

PATCH /api/v1/vault/keys/{key}

Create or update a key-value pair in the personal encrypted vault. Values can be any UTF-8 string (JSON, encrypted data, plain text). The API does not validate content — encryption is highly recommended for sensitive data.

Caution

A 200 response indicates the key was updated; a 201 response indicates it was created. The vault enforces a global storage limit; exceeding it returns 413 VAULT_LIMIT_EXCEEDED.

Parameters

Name	In	Type	Required	Description
realm_id	query	string	No	Target a specific realm (24-char hex). When omitted and not on a realm subdomain, defaults to global scope (realm_id = ""). Case-insensitive — uppercase is normalized to lowercase.
key	path	string	Yes	Vault key name (alphanumeric, dots, underscores, hyphens)

Request Body

Field	Type	Required	Description
value	string	Yes	Value to store (any UTF-8 string: JSON, encrypted data, plain text, etc.)
metadata	object	No	Optional JSON metadata (max 256KB). Useful for file uploads (content-type, filename, upload date, etc.). Must be valid JSON or null. Counts toward total vault storage.

cURL

curl -X PATCH "https://api.hoody.com/api/v1/vault/keys/api-keys" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "{\"api_key\": \"sk_test_123456\", \"encrypted\": true}",
    "metadata": {
      "filename": "api-keys.json",
      "content_type": "application/json",
      "created_by": "admin",
      "purpose": "Production API keys"
    }
  }'

SDK

const { data, error } = await client.api.vault.set({
  key: "api-keys",
  data: {
    value: "{\"api_key\": \"sk_test_123456\", \"encrypted\": true}",
    metadata: {
      filename: "api-keys.json",
      content_type: "application/json",
      created_by: "admin",
      purpose: "Production API keys",
    },
  },
});

Response 200

{
  "statusCode": 200,
  "message": "Vault key updated successfully",
  "data": {
    "key": "my-encrypted-notes",
    "realm_id": "507f1f77bcf86cd799439011",
    "value": "{\"notes\": \"My important notes\", \"encrypted\": true}",
    "metadata": {},
    "size_bytes": 53,
    "created_at": "2025-11-14T18:00:00.000Z",
    "updated_at": "2025-11-14T18:15:00.000Z"
  }
}

Response 201

{
  "statusCode": 201,
  "message": "Vault key created successfully",
  "data": {
    "key": "my-encrypted-notes",
    "realm_id": "507f1f77bcf86cd799439011",
    "value": "{\"notes\": \"My important notes\", \"encrypted\": true}",
    "metadata": {},
    "size_bytes": 53,
    "created_at": "2025-11-14T18:00:00.000Z",
    "updated_at": "2025-11-14T18:00:00.000Z"
  }
}

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

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

413

{
  "statusCode": 413,
  "error": "Payload Too Large",
  "message": "Vault storage limit exceeded."
}

Error Code	Title	Description	Resolution
VAULT_LIMIT_EXCEEDED	Vault Storage Limit Exceeded	The operation would exceed your vault storage limit.	Delete existing keys to free up space or contact support to increase your limit.

GET /api/v1/vault/stats

Retrieve statistics about vault usage. total_keys and total_size_bytes are scoped to the current realm. limit_mb, remaining_mb, and used_percentage reflect global vault usage across all realms.

Parameters

Name	In	Type	Required	Description
realm_id	query	string	No	Target a specific realm (24-char hex). When omitted and not on a realm subdomain, defaults to global scope (realm_id = ""). Case-insensitive — uppercase is normalized to lowercase.

cURL

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

SDK

const { data, error } = await client.api.vault.getStats();

Response 200

{
  "statusCode": 200,
  "message": "Vault statistics retrieved successfully",
  "data": {
    "total_keys": 5,
    "total_size_bytes": 10240,
    "total_size_mb": 0.009766,
    "limit_mb": 50,
    "used_percentage": 0.02,
    "remaining_mb": 49.990234
  }
}

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

DELETE /api/v1/vault/keys/{key}

Permanently delete a key-value pair from the encrypted vault. This action cannot be undone.

Parameters

Name	In	Type	Required	Description
realm_id	query	string	No	Target a specific realm (24-char hex). When omitted and not on a realm subdomain, defaults to global scope (realm_id = ""). Case-insensitive — uppercase is normalized to lowercase.
key	path	string	Yes	Vault key name (alphanumeric, dots, underscores, hyphens)

cURL

curl -X DELETE "https://api.hoody.com/api/v1/vault/keys/my-encrypted-notes" \
  -H "Authorization: Bearer <token>"

SDK

const { data, error } = await client.api.vault.delete({
  key: "my-encrypted-notes",
});

Response 200

{
  "statusCode": 200,
  "message": "Vault key deleted successfully"
}

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": "Vault key not found."
}

Error Code	Title	Description	Resolution
VAULT_KEY_NOT_FOUND	Vault Key Not Found	The specified key does not exist in your vault.	Verify the key name is correct.

DELETE /api/v1/vault

Permanently delete all keys and values from the encrypted vault. This action cannot be undone.

Danger

This operation is destructive and irreversible. All keys and values in the vault will be permanently removed.

Parameters

Name	In	Type	Required	Description
realm_id	query	string	No	Target a specific realm (24-char hex). When omitted and not on a realm subdomain, defaults to global scope (realm_id = ""). Case-insensitive — uppercase is normalized to lowercase.

cURL

curl -X DELETE "https://api.hoody.com/api/v1/vault" \
  -H "Authorization: Bearer <token>"

SDK

const { data, error } = await client.api.vault.clear();

Response 200

{
  "statusCode": 200,
  "message": "Vault cleared successfully",
  "data": {
    "deleted_count": 5
  }
}

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