Storage Shares

Storage shares let one container expose a directory to another container or to every container in a project. Use these endpoints to create, inspect, update, and remove shares, and to let receiving containers accept or reject the shares that target them.

Discovering Shares

GET /api/v1/containers/{id}/storage/incoming

Get all shares targeting this container, including direct container shares and project-wide shares. The response deduplicates overlapping shares (direct shares take priority over project shares) and excludes self-shares and expired shares.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Container ID

cURL

curl -X GET https://api.hoody.com/api/v1/containers/{id}/storage/incoming \
  -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 });

const result = await client.api.storageShares.listIncoming(id);
console.log(result.data);

200

{
  "statusCode": 200,
  "message": "Incoming shares retrieved successfully",
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "source_container_id": "507f1f77bcf86cd799439022",
      "source_path": "/home/app/shared-data",
      "target_container_id": "507f1f77bcf86cd799439033",
      "target_project_id": null,
      "target_type": "container",
      "mode": "readonly",
      "enabled": true,
      "status": "active",
      "status_message": null,
      "expires_at": 1735689599,
      "created_by": "507f1f77bcf86cd799439044",
      "created_at": "2025-01-15T10:30:00.000Z",
      "updated_at": "2025-01-15T10:30:00.000Z"
    },
    {
      "id": "507f1f77bcf86cd799439077",
      "source_container_id": "507f1f77bcf86cd799439088",
      "source_path": "/opt/shared-libs",
      "target_container_id": null,
      "target_project_id": "507f1f77bcf86cd799439055",
      "target_type": "project",
      "mode": "readonly",
      "enabled": true,
      "status": "active",
      "status_message": null,
      "expires_at": null,
      "created_by": "507f1f77bcf86cd799439044",
      "created_at": "2025-01-01T00:00:00.000Z",
      "updated_at": "2025-01-01T00:00:00.000Z"
    }
  ]
}

401

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

403

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

404

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

GET /api/v1/storage/incoming

Get every share targeting any container you own across all projects. Shows what storage you are receiving from others.

Parameters

Name	In	Type	Required	Description
realm_id	query	string	No	Filter by realm ID. Alternative to using realm subdomain in URL.

cURL

curl -X GET https://api.hoody.com/api/v1/storage/incoming \
  -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 });

const result = await client.api.storageShares.listIncomingGlobalIterator();
console.log(result.data);

200

{
  "statusCode": 200,
  "message": "All incoming shares retrieved successfully",
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "source_container_id": "507f1f77bcf86cd799439022",
      "source_path": "/home/app/shared-data",
      "target_container_id": "507f1f77bcf86cd799439033",
      "target_project_id": null,
      "target_type": "container",
      "mode": "readonly",
      "enabled": true,
      "status": "active",
      "status_message": null,
      "expires_at": 1735689599,
      "created_by": "507f1f77bcf86cd799439044",
      "created_at": "2025-01-15T10:30:00.000Z",
      "updated_at": "2025-01-15T10:30:00.000Z"
    }
  ]
}

401

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

GET /api/v1/containers/{id}/storage/shares

List all shares created from a single source container. Use query parameters to narrow by target type, label, status, or enabled state.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Source container ID
target_type	query	string	No	Filter by target type. One of container, project.
label	query	string	No	Filter by label.
status	query	string	No	Filter by status. One of active, failed.
enabled	query	string	No	Filter by enabled status. One of true, false.
include_expired	query	string	No	Include expired shares. One of true, false. Default: false.
realm_id	query	string	No	Filter by realm ID. Alternative to using realm subdomain in URL.

cURL

curl -X GET "https://api.hoody.com/api/v1/containers/{id}/storage/shares?target_type=container&status=active" \
  -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 });

const result = await client.api.storageShares.listIterator(id, { target_type: 'container', status: 'active' });
console.log(result.data);

200

{
  "statusCode": 200,
  "message": "Storage shares retrieved successfully",
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "source_container_id": "507f1f77bcf86cd799439022",
      "source_path": "/home/app/shared-data",
      "target_container_id": "507f1f77bcf86cd799439033",
      "target_project_id": null,
      "target_type": "container",
      "mode": "readonly",
      "alias": "prod-data-share",
      "label": "production",
      "description": "Shared application data directory",
      "enabled": true,
      "status": "active",
      "status_message": null,
      "expires_at": 1735689599,
      "expiry_notified": false,
      "created_by": "507f1f77bcf86cd799439044",
      "realm_ids": ["507f1f77bcf86cd7994390aa"],
      "created_at": "2025-01-15T10:30:00.000Z",
      "updated_at": "2025-01-15T10:30:00.000Z"
    },
    {
      "id": "507f1f77bcf86cd799439066",
      "source_container_id": "507f1f77bcf86cd799439022",
      "source_path": "/var/log/app",
      "target_container_id": null,
      "target_project_id": "507f1f77bcf86cd799439055",
      "target_type": "project",
      "mode": "readwrite",
      "alias": null,
      "label": "logs",
      "description": "Application logs shared with project",
      "enabled": true,
      "status": "active",
      "status_message": null,
      "expires_at": null,
      "expiry_notified": false,
      "created_by": "507f1f77bcf86cd799439044",
      "realm_ids": ["507f1f77bcf86cd7994390aa"],
      "created_at": "2025-01-10T08:00:00.000Z",
      "updated_at": "2025-01-10T08:00:00.000Z"
    }
  ]
}

401

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

403

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

GET /api/v1/storage/shares

List every storage share you have created across all your containers. Returns the share from the creator’s perspective, including alias, label, description, and realm membership.

Parameters

Name	In	Type	Required	Description
realm_id	query	string	No	Filter by realm ID. Alternative to using realm subdomain in URL.

cURL

curl -X GET https://api.hoody.com/api/v1/storage/shares \
  -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 });

const result = await client.api.storageShares.listGlobalIterator();
console.log(result.data);

200

{
  "statusCode": 200,
  "message": "All storage shares retrieved successfully",
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "source_container_id": "507f1f77bcf86cd799439022",
      "source_path": "/home/app/shared-data",
      "target_container_id": "507f1f77bcf86cd799439033",
      "target_project_id": null,
      "target_type": "container",
      "mode": "readonly",
      "alias": "prod-data-share",
      "label": "production",
      "description": "Shared application data directory",
      "enabled": true,
      "status": "active",
      "status_message": null,
      "expires_at": 1735689599,
      "expiry_notified": false,
      "created_by": "507f1f77bcf86cd799439044",
      "realm_ids": ["507f1f77bcf86cd7994390aa"],
      "created_at": "2025-01-15T10:30:00.000Z",
      "updated_at": "2025-01-15T10:30:00.000Z"
    }
  ]
}

401

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

GET /api/v1/containers/{id}/storage/shares/{shareId}

Retrieve details of a single storage share, identified by the source container ID and the share ID.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Source container ID
shareId	path	string	Yes	Share ID

cURL

curl -X GET https://api.hoody.com/api/v1/containers/{id}/storage/shares/{shareId} \
  -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 });

const result = await client.api.storageShares.get(id, shareId);
console.log(result.data);

200

{
  "statusCode": 200,
  "message": "Storage share retrieved successfully",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "source_container_id": "507f1f77bcf86cd799439022",
    "source_path": "/home/app/shared-data",
    "target_container_id": "507f1f77bcf86cd799439033",
    "target_project_id": null,
    "target_type": "container",
    "mode": "readonly",
    "alias": "prod-data-share",
    "label": "production",
    "description": "Shared application data directory",
    "enabled": true,
    "status": "active",
    "status_message": null,
    "expires_at": 1735689599,
    "expiry_notified": false,
    "created_by": "507f1f77bcf86cd799439044",
    "realm_ids": ["507f1f77bcf86cd7994390aa"],
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T10:30:00.000Z"
  }
}

401

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

403

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

404

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

Creating Shares

POST /api/v1/containers/{id}/storage/shares

Share a directory from a source container to either a specific target container or to an entire project. The share is created and automatically mounted on the target(s).

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Source container ID

Request Body

Field	Type	Required	Description
source_path	string	Yes	Absolute path inside the source container. Character whitelist: a-z A-Z 0-9 / - _. Path normalization is applied; .., null bytes, and system paths (/proc/*, /sys/*, /dev/*, /boot/*, /run/*, /var/run/*) are rejected.
target_container_id	string	No	Target container ID for a 1:1 share. Mutually exclusive with target_project_id.
target_project_id	string	No	Target project ID for a project-wide share that auto-mounts on every container in the project. Mutually exclusive with target_container_id.
mode	string	Yes	Mount mode. One of readonly, readwrite.
alias	string	No	Optional human-friendly alias (lowercase alphanumeric, hyphens, underscores; 3-63 chars).
label	string	No	Optional label for grouping shares (lowercase alphanumeric, hyphens, underscores; 3-63 chars).
description	string	No	Optional description (up to 1000 chars).
enabled	boolean	No	Whether the share is enabled on creation (default: true). Disabled shares remain in the database but are not mounted.
expires_at	number	No	Unix timestamp (seconds) at which the share is auto-deleted. Omit for no expiry.

cURL

curl -X POST https://api.hoody.com/api/v1/containers/{id}/storage/shares \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "source_path": "/home/shared/documents",
    "target_container_id": "507f1f77bcf86cd799439033",
    "mode": "readonly",
    "alias": "shared-docs",
    "label": "documentation",
    "description": "Read-only access to team documentation"
  }'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

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

const result = await client.api.storageShares.create(id, {
  source_path: '/home/shared/documents',
  target_container_id: '507f1f77bcf86cd799439033',
  mode: 'readonly',
  alias: 'shared-docs',
  label: 'documentation',
  description: 'Read-only access to team documentation'
});
console.log(result.data);

201

{
  "statusCode": 201,
  "message": "Storage share created successfully",
  "data": {
    "id": "507f1f77bcf86cd799439020",
    "source_container_id": "507f1f77bcf86cd799439012",
    "source_path": "/data/shared",
    "target_container_id": null,
    "target_project_id": "507f1f77bcf86cd799439010",
    "target_type": "project",
    "mode": "readonly",
    "alias": "team-shared-data",
    "label": "production",
    "description": "Shared project files for team collaboration",
    "enabled": true,
    "status": "active",
    "status_message": null,
    "expires_at": 1738252800,
    "expiry_notified": false,
    "created_by": "507f1f77bcf86cd799439001",
    "realm_ids": ["507f1f77bcf86cd7994390aa"],
    "created_at": "2025-01-29T15:00:00.000Z",
    "updated_at": "2025-01-29T15:00:00.000Z"
  }
}

400

{
  "statusCode": 400,
  "error": "VALIDATION_ERROR",
  "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_PATH	Invalid Path	The provided source or destination path is invalid. Kernel paths like /proc, /sys, /dev are not allowed	Provide a valid, non-kernel path for the storage share
SELF_SHARE	Cannot Share to Self	A container cannot share a directory with itself	Choose a different target container or project

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

Error Code	Title	Description	Resolution
CONTAINER_NOT_FOUND	Container not found	The requested container does not exist or you do not have permission to access it	Verify the container ID is correct and that you have access to the project it belongs to
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": "Storage share already exists."
}

Error Code	Title	Description	Resolution
SHARE_ALREADY_EXISTS	Share Already Exists	A share with the same source path and target already exists	Update the existing share or choose a different target

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

Modifying Shares

PATCH /api/v1/containers/{id}/storage/shares/{shareId}

Update properties of an existing storage share. Only the fields you include are changed. Pass null for alias, label, description, or expires_at to clear them.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Source container ID
shareId	path	string	Yes	Share ID

Request Body

Field	Type	Required	Description
mode	string	No	Mount mode. One of readonly, readwrite.
alias	string	No	Alias (3-63 chars, lowercase alphanumeric with hyphens/underscores). Use null to remove.
label	string	No	Label (3-63 chars, lowercase alphanumeric with hyphens/underscores). Use null to remove.
description	string	No	Description (up to 1000 chars). Use null to remove.
enabled	boolean	No	Enable or disable the share.
expires_at	number	No	Unix timestamp (seconds) when the share expires. Use null for no expiry.

cURL

curl -X PATCH https://api.hoody.com/api/v1/containers/{id}/storage/shares/{shareId} \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "readwrite",
    "alias": "prod-data-rw",
    "description": "Updated to read-write access",
    "expires_at": null
  }'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

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

const result = await client.api.storageShares.update(id, shareId, {
  mode: 'readwrite',
  alias: 'prod-data-rw',
  description: 'Updated to read-write access',
  expires_at: null
});
console.log(result.data);

200

{
  "statusCode": 200,
  "message": "Storage share updated successfully",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "source_container_id": "507f1f77bcf86cd799439022",
    "source_path": "/home/app/shared-data",
    "target_container_id": "507f1f77bcf86cd799439033",
    "target_project_id": null,
    "target_type": "container",
    "mode": "readwrite",
    "alias": "prod-data-rw",
    "label": "production",
    "description": "Updated to read-write access",
    "enabled": true,
    "status": "active",
    "status_message": null,
    "expires_at": null,
    "expiry_notified": false,
    "created_by": "507f1f77bcf86cd799439044",
    "realm_ids": ["507f1f77bcf86cd7994390aa"],
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T14:45:00.000Z"
  }
}

400

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

401

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

403

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

404

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

PATCH /api/v1/containers/{id}/storage/incoming/{shareId}/mount

Let the receiving container accept or reject an incoming share. The creator’s enabled flag and the receiver’s mount flag must both be true for the share to actually be mounted.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Target container ID (the receiver container)
shareId	path	string	Yes	Share ID to toggle

Request Body

Field	Type	Required	Description
mount	boolean	Yes	Set to true to accept and mount the share, false to reject or unmount it.

cURL

curl -X PATCH https://api.hoody.com/api/v1/containers/{id}/storage/incoming/{shareId}/mount \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "mount": true }'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

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

const result = await client.api.storageShares.toggleIncomingMount(id, shareId, { mount: true });
console.log(result.data);

200

{
  "statusCode": 200,
  "message": "Share enabled for mounting successfully",
  "data": {
    "share": {
      "id": "507f1f77bcf86cd799439011",
      "source_container_id": "507f1f77bcf86cd799439022",
      "source_path": "/home/app/shared-data",
      "target_container_id": "507f1f77bcf86cd799439033",
      "target_project_id": null,
      "target_type": "container",
      "mode": "readonly",
      "alias": "prod-data-share",
      "label": "production",
      "description": "Shared application data directory",
      "enabled": true,
      "status": "active",
      "status_message": null,
      "expires_at": 1735689599,
      "expiry_notified": false,
      "created_by": "507f1f77bcf86cd799439044",
      "realm_ids": ["507f1f77bcf86cd7994390aa"],
      "created_at": "2025-01-15T10:30:00.000Z",
      "updated_at": "2025-01-15T14:45:00.000Z"
    },
    "override": {
      "id": "507f1f77bcf86cd799439099",
      "share_id": "507f1f77bcf86cd799439011",
      "container_id": "507f1f77bcf86cd799439033",
      "mount": true,
      "created_at": "2025-01-15T14:45:00.000Z",
      "updated_at": "2025-01-15T14:45:00.000Z"
    }
  }
}

400

{
  "statusCode": 400,
  "error": "VALIDATION_ERROR",
  "message": "This share does not target the specified container",
  "data": {
    "share_id": "507f1f77bcf86cd799439011",
    "container_id": "507f1f77bcf86cd799439099",
    "target_container_id": "507f1f77bcf86cd799439033",
    "target_project_id": null
  }
}

401

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

403

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

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Share or container not found"
}

Removing Shares

DELETE /api/v1/storage/shares/{shareId}

Delete a storage share by its globally unique share ID. The container ID is not required. The share is automatically unmounted from all targets.

Parameters

Name	In	Type	Required	Description
shareId	path	string	Yes	Share ID (globally unique, no container ID needed)

cURL

curl -X DELETE https://api.hoody.com/api/v1/storage/shares/{shareId} \
  -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.storageShares.delete(shareId);

200

{
  "statusCode": 200,
  "message": "Storage share deleted successfully"
}

401

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

403

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

404

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