Storage Shares

Overview

Storage shares let a source container expose a directory to a target container (1:1) or to every container in a target project (project-wide). The source container controls what is shared (the path), while the server infrastructure determines where the path is mounted inside the target. All share paths are absolute and restricted to a character whitelist (a-z A-Z 0-9 / - _ .); system paths (/proc, /sys, /dev, /boot, /run, /var/run) and traversal sequences (..) are rejected.

Use these endpoints to create, inspect, update, and delete shares; list shares a container is exporting; list shares a container is receiving; and let a target container accept or reject incoming mounts.

Listing Shares

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

List all shares originating from the specified source container. Use query parameters to narrow results.

Parameters

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

Response

{
  "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",
      "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_project_id": "507f1f77bcf86cd799439055",
      "target_container_id": null,
      "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",
      "created_at": "2025-01-10T08:00:00.000Z",
      "updated_at": "2025-01-10T08:00:00.000Z"
    }
  ]
}

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

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

SDK Usage

// List all shares from the source container
await client.api.storageShares.listIterator(id)

// Filter by target type and status
await client.api.storageShares.listIterator(id, {
  target_type: 'container',
  status: 'active',
  enabled: 'true'
})

cURL

curl -X GET "https://api.hoody.icu/api/v1/containers/507f1f77bcf86cd799439022/storage/shares?status=active&enabled=true" \
  -H "Authorization: Bearer <token>"

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

List all shares targeting this container, including both direct (1:1) shares and project-level shares. Results are deduplicated so that a direct share takes priority over a project share for the same source path. Self-shares and expired shares are filtered out.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Container ID

Response

{
  "statusCode": 200,
  "message": "Incoming shares retrieved successfully",
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "source_container_id": "507f1f77bcf86cd799439022",
      "source_path": "/etc/app/config",
      "target_container_id": "507f1f77bcf86cd799439033",
      "target_project_id": null,
      "target_type": "container",
      "mode": "readonly",
      "enabled": true,
      "status": "active",
      "status_message": null,
      "expires_at": null,
      "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_project_id": "507f1f77bcf86cd799439055",
      "target_container_id": null,
      "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"
    }
  ]
}

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

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

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

SDK Usage

await client.api.storageShares.listIncoming(id)

cURL

curl -X GET "https://api.hoody.icu/api/v1/containers/507f1f77bcf86cd799439033/storage/incoming" \
  -H "Authorization: Bearer <token>"

`GET /api/v1/storage/shares`

List every storage share you have created across all your containers. Use this to audit what you are sharing with others.

Parameters

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

Response

{
  "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",
      "created_at": "2025-01-15T10:30:00.000Z",
      "updated_at": "2025-01-15T10:30:00.000Z"
    }
  ]
}

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

SDK Usage

await client.api.storageShares.listGlobalIterator()

// Or scoped to a realm
await client.api.storageShares.listGlobalIterator({ realm_id: '507f1f77bcf86cd799439055' })

cURL

curl -X GET "https://api.hoody.icu/api/v1/storage/shares" \
  -H "Authorization: Bearer <token>"

`GET /api/v1/storage/incoming`

List all incoming shares targeting your containers across all projects. Shows everything you are receiving from other source containers.

Parameters

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

Response

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

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

SDK Usage

await client.api.storageShares.listIncomingGlobalIterator()

cURL

curl -X GET "https://api.hoody.icu/api/v1/storage/incoming" \
  -H "Authorization: Bearer <token>"

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

Retrieve details of a single storage share by its ID.

Parameters

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

Response

{
  "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",
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T10:30:00.000Z"
  }
}

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

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

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

SDK Usage

await client.api.storageShares.get(id, shareId)

cURL

curl -X GET "https://api.hoody.icu/api/v1/containers/507f1f77bcf86cd799439022/storage/shares/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer <token>"

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

Create a new share. Share a directory from the source container with a specific target container (target_container_id) or with every container in a target project (target_project_id). Only one of those two targets may be supplied. The share is mounted automatically when created.

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 to share. Character whitelist: `a-z A-Z 0-9 / - _ .`. System paths (`/proc`, `/sys`, `/dev`, `/boot`, `/run`, `/var/run`) and `..` traversal are rejected.
`mode`	string	Yes	Mount mode. Allowed values: `readonly`, `readwrite`
`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 (auto-mounts on all containers in the project). Mutually exclusive with `target_container_id`.
`alias`	string	No	Optional human-friendly alias (lowercase alphanumeric with hyphens/underscores, 3-63 chars).
`label`	string	No	Optional grouping label (lowercase alphanumeric with hyphens/underscores, 3-63 chars).
`description`	string	No	Optional free-form description (max 1000 chars).
`enabled`	boolean	No	Whether the share is mounted. Default: `true`. Disabled shares remain in the database but are not mounted.
`expires_at`	number	No	Unix timestamp (seconds) at which the share should auto-expire.

Response

{
  "statusCode": 201,
  "message": "Storage share created successfully",
  "data": {
    "id": "507f1f77bcf86cd799439020",
    "source_container_id": "507f1f77bcf86cd799439012",
    "source_path": "/data/shared",
    "target_project_id": "507f1f77bcf86cd799439010",
    "target_container_id": null,
    "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",
    "created_at": "2025-01-29T15:00:00.000Z",
    "updated_at": "2025-01-29T15:00:00.000Z"
  }
}

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid path provided."
}

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.

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication 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": "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

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

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

SDK Usage

// 1:1 share with a specific target container
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'
})

// Project-wide share with expiration
await client.api.storageShares.create(id, {
  source_path: '/opt/config',
  target_project_id: '507f1f77bcf86cd799439010',
  mode: 'readonly',
  alias: 'app-config',
  label: 'config',
  expires_at: 1738252800
})

cURL

curl -X POST "https://api.hoody.icu/api/v1/containers/507f1f77bcf86cd799439012/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"
  }'

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

Update properties of an existing share. Only the fields you include in the body are modified. To clear an optional field, pass null.

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. Allowed values: `readonly`, `readwrite`
`alias`	string	No	Alias (lowercase alphanumeric with hyphens/underscores, 3-63 chars). Pass `null` to remove.
`label`	string	No	Label (lowercase alphanumeric with hyphens/underscores, 3-63 chars). Pass `null` to remove.
`description`	string	No	Description (max 1000 chars). Pass `null` to remove.
`enabled`	boolean	No	Enable or disable the share. Disabled shares remain in the database but are not mounted.
`expires_at`	number	No	Unix timestamp (seconds) at which the share expires. Pass `null` to never expire.

Response

{
  "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",
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T14:45:00.000Z"
  }
}

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

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

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

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

SDK Usage

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

cURL

curl -X PATCH "https://api.hoody.icu/api/v1/containers/507f1f77bcf86cd799439022/storage/shares/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "readwrite",
    "description": "Updated to read-write access"
  }'

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

Enable or disable mounting of an incoming share on a specific target container. This allows the receiving container owner to accept or reject an incoming share. A share appears in the target container’s /proc/mounts only when both the creator’s enabled flag and the receiver’s mount override are true.

Parameters

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

Request Body

Field	Type	Required	Description
`mount`	boolean	Yes	`true` to accept and mount the share; `false` to reject or unmount it

Response

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

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

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

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

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

SDK Usage

// Accept an incoming share
await client.api.storageShares.toggleIncomingMount(id, shareId, { mount: true })

// Reject an incoming share
await client.api.storageShares.toggleIncomingMount(id, shareId, { mount: false })

cURL

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

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

Remove a storage share by ID. Share IDs are globally unique so the source container ID is not required. The share is automatically unmounted from its targets.

Parameters

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

Response

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

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

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

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

SDK Usage

await client.api.storageShares.delete(shareId)

cURL

curl -X DELETE "https://api.hoody.icu/api/v1/storage/shares/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer <token>"

Overview

Listing Shares

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

Parameters

Response

SDK Usage

cURL

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

Parameters

Response

SDK Usage

cURL

GET /api/v1/storage/shares

Parameters

Response

SDK Usage

cURL

GET /api/v1/storage/incoming

Parameters

Response

SDK Usage

cURL

Share Management

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

Parameters

Response

SDK Usage

cURL

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

Parameters

Request Body

Response

SDK Usage

cURL

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

Parameters

Request Body

Response

SDK Usage

cURL

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

Parameters

Request Body

Response

SDK Usage

cURL

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

Parameters

Response

SDK Usage

cURL

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

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

`GET /api/v1/storage/shares`

`GET /api/v1/storage/incoming`

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

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

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

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

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