User Profile Management

Use these endpoints to read and update Hoody user profiles, audit account security, browse activity logs, manage free-tier onboarding, and read or write entries in your personal encrypted vault. Every endpoint on this page is a control-plane operation served from https://api.hoody.com. Authenticate with a first-party JWT for account-setting endpoints (onboarding milestones and invite redemption) or with an auth token for everything else, sent in the Authorization header as Bearer <token>.

User Profile

`GET /api/v1/users/{id}`

Retrieve a user profile by ID. Admins can read any account; regular users may only read their own. The endpoint continues to work for banned accounts (read-only access). When the caller is an auth token that lacks the resources.read_account permission, the response is reduced to identity fields and email / account PII are omitted.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	User ID to retrieve (24-character hexadecimal identifier)

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

import { HoodyClient } from 'hoody-sdk';

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

await client.api.users.get('507f1f77bcf86cd799439011');

{
  "statusCode": 200,
  "message": "User retrieved successfully",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "username": "john_doe",
    "alias": "John Doe",
    "email": "john.doe@example.com",
    "public_key": "a1b2c3d4e5f6789012345678901234567890abcdefabcdefabcdefabcdef1234",
    "is_admin": false,
    "is_banned": false,
    "email_verified": true,
    "avatar_url": "https://avatars.githubusercontent.com/u/1234567",
    "signup_method": "email",
    "free_tier_unlocked": true,
    "free_tier_unlocked_at": "2026-06-24T10:00:00.000Z",
    "free_tier_unlock_source": "invite_code",
    "onboarding": {
      "hub_tour_v1": "2026-06-30T10:00:00.000Z"
    },
    "metadata": {
      "department": "Engineering",
      "location": "San Francisco"
    },
    "created_at": "2024-12-01T10:00:00.000Z",
    "updated_at": "2025-01-15T10:30:00.000Z"
  }
}

{
  "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`)

{
  "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

{
  "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

{
  "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

`PUT /api/v1/users/{id}`

Update a user profile. Regular accounts may change their own display alias and password (the request must include current_password for verification). Admins may update any account and may set the is_admin and is_banned flags. When the caller is an auth token that lacks the resources.read_account permission, the returned profile is reduced to identity fields and email / account PII are omitted.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	User ID to update (24-character hexadecimal identifier)

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; may include nested objects
`password`	string	No	New password, at least 12 characters and three of four character classes; requires `current_password` for verification
`current_password`	string	No	Current password (required when `password` is set)
`is_admin`	boolean	No	Admin status (admin-only field)
`is_banned`	boolean	No	Ban status; banned accounts cannot call the API

curl -X PUT "https://api.hoody.com/api/v1/users/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "alias": "John Smith",
    "current_password": "OldSecretPhrase42!",
    "password": "NewSecretPhrase42!",
    "metadata": { "department": "Engineering", "location": "San Francisco" }
  }'

import { HoodyClient } from 'hoody-sdk';

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

await client.api.users.update('507f1f77bcf86cd799439011', {
  alias: 'John Smith',
  current_password: 'OldSecretPhrase42!',
  password: 'NewSecretPhrase42!',
  metadata: { department: 'Engineering', location: 'San Francisco' },
});

{
  "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,
    "email_verified": true,
    "avatar_url": "https://avatars.githubusercontent.com/u/1234567",
    "signup_method": "email",
    "free_tier_unlocked": true,
    "free_tier_unlocked_at": "2026-06-24T10:00:00.000Z",
    "free_tier_unlock_source": "invite_code",
    "onboarding": {
      "hub_tour_v1": "2026-06-30T10:00:00.000Z"
    },
    "metadata": {},
    "created_at": "2024-12-01T10:00:00.000Z",
    "updated_at": "2025-01-15T14:45:00.000Z"
  }
}

{
  "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
`RESERVED_IDENTITY`	Display name is reserved	A small set of display names is refused because they read as official Hoody channels rather than as a person: the brand itself, and authority words such as `admin`, `support`, `billing`, `security` when they appear as a whole word. Ordinary names that merely contain one of those words are not affected, so `Supporter`, `Code`, and `Bill Ing` are all accepted.	Choose a display name that identifies the person or team rather than the platform.

{
  "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

{
  "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	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

{
  "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

Free-Tier Onboarding

`GET /api/v1/users/me/free-tier-status`

Returns whether the beta gate is enabled, whether this account is unlocked, whether it already owns a free server, and (advisory, point-in-time) why a claim is currently blocked. Never attempts a claim. Auth-token callers must hold the resources.read_account permission (account-level status); tokens without it receive 403. JWT / owner callers are unaffected.

This endpoint takes no parameters.

curl -X GET "https://api.hoody.com/api/v1/users/me/free-tier-status" \
  -H "Authorization: Bearer <token>"

import { HoodyClient } from 'hoody-sdk';

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

await client.api.users.getFreeTierStatus();

{
  "statusCode": 200,
  "message": "Free-tier status retrieved",
  "data": {
    "gate_enabled": true,
    "unlocked": false,
    "has_free_server": false,
    "can_claim": false,
    "claim_blocked_reason": "invite_required",
    "signup_code_failed": false
  }
}

{
  "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

{
  "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

{
  "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

`POST /api/v1/users/me/redeem-invite`

Redeem a single-use invite code to unlock free-tier server claiming during the beta, then immediately provision a free server. Idempotent if already unlocked. No-op (no code consumed) when the beta gate is disabled. Requires a first-party JWT; auth tokens, HTTP Basic, and impersonation are rejected.

Request Body

Field	Type	Required	Description
`code`	string	Yes	The invite code (case / format-insensitive, 1-64 characters)

curl -X POST "https://api.hoody.com/api/v1/users/me/redeem-invite" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "HOODY-7Q4K-9F2M-3B8T-XR5W-2HKD-1"
  }'

import { HoodyClient } from 'hoody-sdk';

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

await client.api.users.redeemInviteCode({ code: 'HOODY-7Q4K-9F2M-3B8T-XR5W-2HKD-1' });

{
  "statusCode": 200,
  "message": "Invite code redeemed. Your free server is being prepared.",
  "data": {
    "unlocked": true,
    "required": true,
    "claim_blocked_reason": "none",
    "server": {
      "id": "67e89abc123def456789abcd",
      "hostname": "67e89abc123def456789abcd-890abcdef12345678901cdef.node-us.containers.hoody.com",
      "region": "node-us"
    },
    "project": {
      "id": "67e89abc123def456789abcd",
      "name": "Default Project"
    },
    "container": {
      "id": "890abcdef12345678901cdef",
      "hostname": "67e89abc123def456789abcd-890abcdef12345678901cdef.node-us.containers.hoody.com"
    }
  }
}

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "This invite code is invalid, expired, or already used."
}

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_INVITE_CODE`	Invalid invite code	The submitted invite code could not be redeemed because it is unknown, already used, disabled, or expired.	Check the code for typos, or request a new invite code from an administrator.

{
  "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

{
  "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

{
  "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

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

Manually claim a free-tier server and create the default project and container. Idempotent; safe to call if already provisioned.

Request Body

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

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

import { HoodyClient } from 'hoody-sdk';

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

await client.api.users.retrySetup({ region: 'node-us' });

{
  "statusCode": 200,
  "data": {
    "server": {
      "id": "67e89abc123def456789abcd",
      "hostname": "67e89abc123def456789abcd-890abcdef12345678901cdef.node-us.containers.hoody.com",
      "region": "node-us"
    },
    "project": {
      "id": "67e89abc123def456789abcd",
      "name": "Default Project"
    },
    "container": {
      "id": "890abcdef12345678901cdef",
      "hostname": "67e89abc123def456789abcd-890abcdef12345678901cdef.node-us.containers.hoody.com"
    },
    "blocked_reason": null
  }
}

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "An invite code is required to claim your free server during the beta."
}

Error Code	Title	Description	Resolution
`FREE_TIER_INVITE_REQUIRED`	Invite code required	The beta access gate is enabled and this account has not been unlocked, so it cannot claim a free server yet.	Redeem your invite code at `POST /api/v1/users/me/redeem-invite`, or ask an administrator to validate your account by email.
`INSUFFICIENT_PERMISSIONS`	Insufficient permissions	You do not have the required permissions to perform this action	Contact the resource owner or administrator to request access

`POST /api/v1/users/me/onboarding`

Idempotently records a per-account onboarding / UI milestone (key to ISO timestamp). Used by the /auth/home first-run tour (milestone hub_tour_v1) and reusable for any future onboarding step. Setting an already-present milestone is a no-op; the original timestamp is kept.

Request Body

Field	Type	Required	Description
`milestone`	string	Yes	Milestone key, for example `hub_tour_v1`. Must match one of the supported milestone patterns.

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

curl -X POST "https://api.hoody.com/api/v1/users/me/onboarding" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "milestone": "hub_tour_v1"
  }'

import { HoodyClient } from 'hoody-sdk';

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

await client.api.users.markOnboardingMilestone({ milestone: 'hub_tour_v1' });

{
  "statusCode": 200,
  "message": "Milestone recorded",
  "data": {
    "onboarding": {
      "hub_tour_v1": "2026-06-30T10:00:00.000Z"
    }
  }
}

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

Error Code	Title	Description	Resolution
`VALIDATION_ERROR`	Invalid input parameters	The `milestone` key did not match the expected pattern	Check the milestone pattern (`hub_tour_v\d+`, `dashboard_[a-z0-9_]{1,30}`, or `onboarding_[a-z0-9_]{1,30}`) and try again
`ONBOARDING_LIMIT`	Onboarding milestone cap reached	The account already holds the maximum number of distinct onboarding milestones (50).	No action needed; the cap guards against unbounded growth; existing milestones are unaffected.

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

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "This endpoint requires a first-party session JWT."
}

Security History

`GET /api/v1/users/me/security-history`

Returns your own account security history: sign-ins and, on request, rejected attempts and other security events (logout, 2FA changes, OTP outcomes), with IP address, resolved country, source channel, and timestamp, newest first.

History covers the last 180 days, which is platform policy and the same for every account; older logins are purged automatically and cannot be recovered. Login records cannot be edited or deleted by the account holder; the trail is append-only so it stays trustworthy as evidence.

Pass include_failed=true to also see rejected sign-in attempts. A burst of them, or any from a country you have not visited, is the clearest sign someone else is trying to get in. Failures are only recorded when a credential was presented against a real account (an attempt on an unknown address is never recorded, so this cannot be used to test whether an account exists), and are capped at 200 per account per hour; beyond that, further attempts in the same hour are not listed.

Pass include_security=true for other account-security events: logout, 2FA enable / disable, OTP verification outcomes, and backup-code use.

country is resolved in the background after the event is recorded. It is null when the address is not geolocatable at all (private, reserved, or IPv6; these stay null permanently), when the provider returned no country for it, or when resolution has not completed. Treat null as unavailable, never as a location. A null does not necessarily become non-null later: background retries stop once the row ages out of the retry window.

Parameters

Name	In	Type	Required	Description
`page`	query	integer	No	Page number (default 1)
`limit`	query	integer	No	Results per page (default 50)
`include_failed`	query	boolean	No	Also return rejected sign-in attempts against this account. Opt-in: mixing them in by default would make failed attempts look like your own sessions. (default `false`)
`include_security`	query	boolean	No	Also return other account-security events: logout, 2FA enabled / disabled, OTP verification outcomes, backup-code regeneration. (default `false`)

curl -X GET "https://api.hoody.com/api/v1/users/me/security-history?include_failed=true&include_security=true&page=1&limit=50" \
  -H "Authorization: Bearer <token>"

import { HoodyClient } from 'hoody-sdk';

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

await client.api.users.getSecurityHistoryIterator({ include_failed: true, include_security: true, page: 1, limit: 50 });

{
  "statusCode": 200,
  "message": "Login history retrieved successfully",
  "data": [
    {
      "id": "1a9c3592695c087a8f35ceae",
      "event": "login",
      "outcome": "success",
      "ip_address": "203.0.113.42",
      "country": "US",
      "client": "web",
      "created_at": "2026-06-30T10:00:00.000Z"
    },
    {
      "id": "1a9c3592695c087a8f35ceaf",
      "event": "login_failed",
      "outcome": "failed",
      "ip_address": "198.51.100.7",
      "country": "FR",
      "client": "web",
      "created_at": "2026-06-30T09:45:00.000Z"
    }
  ],
  "metadata": {
    "total": 2,
    "page": 1,
    "limit": 50,
    "pages": 1
  }
}

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

Activity Logs

`GET /api/v1/users/auth/activity`

Retrieve activity logs for the authenticated user with optional filtering.

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). Literal 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. Literal values: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`.
`realm_id`	query	string	No	Filter by realm ID

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

import { HoodyClient } from 'hoody-sdk';

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

await client.api.activity.listIterator({ page: 1, limit: 50, errors_only: 'false' });

{
  "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": "203.0.113.42",
      "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.

This endpoint takes no parameters.

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

import { HoodyClient } from 'hoody-sdk';

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

await client.api.activity.getStats();

{
  "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": 365
  }
}

User Vault

`GET /api/v1/vault/keys`

List all keys in your encrypted vault with metadata (key names, sizes, timestamps). Values are not included in this response; use GET /api/v1/vault/keys/{key} to retrieve individual values.

Parameters

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

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

import { HoodyClient } from 'hoody-sdk';

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

await client.api.vault.listIterator();

{
  "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"
    }
  ]
}

{
  "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

{
  "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 your encrypted vault by key name.

Parameters

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

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

import { HoodyClient } from 'hoody-sdk';

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

await client.api.vault.get('my-encrypted-notes');

{
  "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"
  }
}

{
  "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

{
  "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

{
  "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.

`PUT /api/v1/vault/keys/{key}`

Create or update a key-value pair in your 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.

Parameters

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

Request Body

Field	Type	Required	Description
`value`	string	Yes	Value to store. Can be any UTF-8 string: JSON, encrypted data, plain text. The API does not validate or verify the content; encryption is highly recommended for sensitive data such as secrets, passwords, and API keys.
`metadata`	object	No	Optional JSON metadata (max 256 KB). Useful for file uploads to store content-type, filename, upload date, and so on. Must be valid JSON or `null`. Counts toward storage.

curl -X PUT "https://api.hoody.com/api/v1/vault/keys/api-keys.json" \
  -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",
      "purpose": "Production API keys"
    }
  }'

import { HoodyClient } from 'hoody-sdk';

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

await client.api.vault.set('api-keys.json', {
  value: '{"api_key": "sk_test_123456", "encrypted": true}',
  metadata: {
    filename: 'api-keys.json',
    content_type: 'application/json',
    purpose: 'Production API keys',
  },
});

{
  "statusCode": 200,
  "message": "Vault key updated successfully",
  "data": {
    "key": "api-keys.json",
    "realm_id": "507f1f77bcf86cd799439011",
    "value": "{\"api_key\": \"sk_test_123456\", \"encrypted\": true}",
    "metadata": {
      "filename": "api-keys.json",
      "content_type": "application/json",
      "purpose": "Production API keys"
    },
    "size_bytes": 1284,
    "created_at": "2025-11-14T18:00:00.000Z",
    "updated_at": "2025-11-14T18:15:00.000Z"
  }
}

{
  "statusCode": 201,
  "message": "Vault key created successfully",
  "data": {
    "key": "api-keys.json",
    "realm_id": "507f1f77bcf86cd799439011",
    "value": "{\"api_key\": \"sk_test_123456\", \"encrypted\": true}",
    "metadata": {
      "filename": "api-keys.json",
      "content_type": "application/json",
      "purpose": "Production API keys"
    },
    "size_bytes": 1284,
    "created_at": "2025-11-14T18:00:00.000Z",
    "updated_at": "2025-11-14T18:00:00.000Z"
  }
}

{
  "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 (missing `value`, malformed `metadata`, invalid key name, etc.)	Check the error message for specific field requirements and correct your input

{
  "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

{
  "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

{
  "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.

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

Permanently delete a single key-value pair from your vault. The action cannot be undone.

Parameters

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

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

import { HoodyClient } from 'hoody-sdk';

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

await client.api.vault.delete('api-keys.json');

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

{
  "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

{
  "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

{
  "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`

Parameters

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

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

import { HoodyClient } from 'hoody-sdk';

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

await client.api.vault.clear();

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

{
  "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

{
  "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/stats`

Return vault usage statistics. 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-character hex). When omitted and not on a realm subdomain, defaults to global scope (`realm_id = ""`). Case-insensitive; uppercase is normalized to lowercase.

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

import { HoodyClient } from 'hoody-sdk';

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

await client.api.vault.getStats();

{
  "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
  }
}

{
  "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

{
  "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