Storage Shares

Storage shares let you expose a directory from one container to another container or to an entire project. The source container controls what path is shared; the target mount path is determined automatically by the server infrastructure. Shares support read-only and read-write modes, optional expiration, and can be toggled on the receiving side.

Use the endpoints on this page to create, list, inspect, update, and delete shares, as well as to view and accept incoming shares targeted at your containers.

---

Incoming Shares

Incoming shares are the receiver view — storage that other containers are sharing with a specific target. They include both 1:1 container shares and project-wide shares, deduplicated so that direct shares take priority over project shares. Self-shares and expired shares are excluded.

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

Get all shares targeting this container (both direct shares and project-level shares). Shows what storage this container is configured to receive. Includes deduplication (direct shares take priority over project shares) and filters out self-shares and expired shares.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Container ID

Response

200

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

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

SDK Usage

const { data } = await client.api.storageShares.listIncoming({
  id: "507f1f77bcf86cd799439033"
});

GET /api/v1/storage/incoming

Get all shares targeting your containers 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.

Response

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

SDK Usage

const { data } = await client.api.storageShares.listIncomingGlobalIterator({});

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

Enable or disable mounting of an incoming share. Allows the target container owner to accept or reject incoming shares. Both the creator’s enabled flag and the receiver’s mount flag must be true for the share to appear in container configuration.

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	Set to true to accept and mount the share, false to reject/unmount it

{
  "mount": true
}

Response

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

SDK Usage

await client.api.storageShares.toggleIncomingMount({
  id: "507f1f77bcf86cd799439033",
  shareId: "507f1f77bcf86cd799439011",
  data: { mount: true }
});

---

Outgoing Shares (Creator View)

Outgoing shares are what your containers are exposing to others. The endpoints below let you list, inspect, create, update, and delete shares. Share IDs are globally unique.

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

List all shares originating from this source container. Use query parameters to narrow results 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. 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

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

401

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

403

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

SDK Usage

const { data } = await client.api.storageShares.listIterator({
  id: "507f1f77bcf86cd799439022",
  target_type: "container",
  enabled: "true"
});

GET /api/v1/storage/shares

List all storage shares you have created across all your containers (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

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

SDK Usage

const { data } = await client.api.storageShares.listGlobalIterator({});

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

Retrieve details of a specific storage share.

Parameters

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

Response

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

SDK Usage

const { data } = await client.api.storageShares.get({
  id: "507f1f77bcf86cd799439022",
  shareId: "507f1f77bcf86cd799439011"
});

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

Share a directory from a source container with a target container or an entire project. The share is automatically mounted on the target(s).

Caution

Source paths are security-hardened: character whitelist is a-z A-Z 0-9 / - _ ., system paths under /proc, /sys, /dev, /boot, /run, and /var/run are blocked, and path traversal (..) is rejected. The target mount path is determined by server infrastructure and cannot be specified by the caller.

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 in the source container to share
target_container_id	string	No	1:1 container share target. Mutually exclusive with target_project_id.
target_project_id	string	No	Project-wide share target. Auto-mounts on all containers in the project. Mutually exclusive with target_container_id.
mode	string	Yes	Mount mode. Allowed values: readonly, readwrite.
alias	string	No	Optional human-friendly alias (lowercase alphanumeric, hyphens, underscores; 3–63 chars)
label	string	No	Optional label for grouping shares (3–63 chars)
description	string	No	Optional description (max 1000 chars)
enabled	boolean	No	Whether to enable the share (default: true)
expires_at	number	No	Unix timestamp (seconds) when the share should expire

{
  "source_path": "/home/shared/documents",
  "target_container_id": "507f1f77bcf86cd799439033",
  "mode": "readonly",
  "alias": "shared-docs",
  "label": "documentation",
  "description": "Read-only access to team documentation"
}

Response

201

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

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "A container cannot share a directory with itself."
}

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

SDK Usage

await client.api.storageShares.create({
  id: "507f1f77bcf86cd799439012",
  data: {
    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 share properties such as mode, alias, label, description, enabled state, and expiration. Only the fields provided in the request body are updated; omit a field to leave it unchanged. Pass null for an explicit clear (where supported).

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 | null	No	Alias (null to remove)
label	string | null	No	Label (null to remove)
description	string | null	No	Description (null to remove)
enabled	boolean	No	Enable or disable the share
expires_at	number | null	No	Unix timestamp (seconds) when the share expires (null to never expire)

{
  "mode": "readwrite",
  "alias": "prod-data-rw",
  "description": "Updated to read-write access",
  "expires_at": null
}

Response

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

SDK Usage

await client.api.storageShares.update({
  id: "507f1f77bcf86cd799439022",
  shareId: "507f1f77bcf86cd799439011",
  data: {
    mode: "readwrite",
    description: "Updated to read-write access"
  }
});

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 target(s).

Parameters

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

Response

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

SDK Usage

await client.api.storageShares.delete({
  shareId: "507f1f77bcf86cd799439011"
});