Overview

Storage shares let you mount a directory from a source container into one or more target containers. Shares can target a single container (1:1) or every container in a project (project-wide). The source container controls what path is shared; target mount paths are assigned automatically by the server.

Use these endpoints to create, list, retrieve, update, toggle, and delete storage shares, and to inspect incoming shares (storage that other containers share with you).

Note

Source paths are security-hardened: the API rejects kernel paths (/proc/*, /sys/*, /dev/*, /boot/*, /run/*, /var/run/*), path traversal (..), and null bytes. Only characters a-z A-Z 0-9 / - _ . are permitted.

---

Viewing incoming shares

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

Get all shares targeting a specific container. Returns both direct shares and project-level shares, with deduplication (direct shares take priority over project shares) and self-shares / expired shares filtered out.

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

SDK usage

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

GET /api/v1/storage/incoming

Get all shares targeting any of your containers across all projects. Useful for an account-wide inventory of incoming storage.

Parameters

Name	In	Type	Required	Description
realm_id	query	string	No	Filter by realm ID. Alternative to using the realm subdomain in the 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 incoming = await client.api.storageShares.listIncomingGlobalIterator({
  realm_id: "507f1f77bcf86cd799439010"
});

---

Listing and retrieving shares

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

List every share that originates from a specific source container. Supports filters by target type, label, status, enabled flag, expiry, and realm.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Source container ID
target_type	query	string	No	Filter by target type. Allowed: container, project.
label	query	string	No	Filter by label
status	query	string	No	Filter by status. Allowed: active, failed.
enabled	query	string	No	Filter by enabled status. Allowed: true, false.
include_expired	query	string	No	Include expired shares. Allowed: true, false. Default: false.
realm_id	query	string	No	Filter by realm ID. Alternative to using the realm subdomain in the 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_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",
      "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 shares = await client.api.storageShares.listIterator({
  id: "507f1f77bcf86cd799439022",
  target_type: "container",
  status: "active",
  include_expired: "false"
});

GET /api/v1/storage/shares

List every storage share you have created across all of 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 the realm subdomain in the 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 shares = await client.api.storageShares.listGlobalIterator();

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

Retrieve the full details of a single 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 share = await client.api.storageShares.get({
  id: "507f1f77bcf86cd799439022",
  shareId: "507f1f77bcf86cd799439011"
});

---

Creating a share

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

Share a directory from a source container to either a single target container or to every container in a target project. The share is automatically mounted on the target(s).

Caution

Specify exactly one of target_container_id or target_project_id. A container cannot share a directory with itself.

Parameters

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

Request Body

Name	Type	Required	Description
source_path	string	Yes	Absolute path inside the source container. Subject to the path-security rules above.
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. Mutually exclusive with target_container_id.
mode	string	Yes	Mount mode. Allowed: readonly, readwrite.
alias	string	No	Optional lowercase alphanumeric alias (3–63 chars, hyphens/underscores allowed).
label	string	No	Optional label for grouping shares (same constraints as alias).
description	string	No	Optional description (max 1000 chars).
enabled	boolean	No	Enable the share on creation. Default: true.
expires_at	number	No	Unix timestamp (seconds) when the share should auto-expire.

Response

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

SDK usage

const share = 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"
  }
});

---

Updating shares

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

Update share properties. Only the fields you include are changed. Pass null to clear alias, label, description, or expires_at.

Parameters

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

Request Body

Name	Type	Required	Description
mode	string	No	Mount mode. Allowed: readonly, readwrite.
alias	string	No	Alias (lowercase alphanumeric, 3–63 chars). Pass null to remove.
label	string	No	Label for grouping shares. Pass null to remove.
description	string	No	Description (max 1000 chars). Pass null to remove.
enabled	boolean	No	Enable or disable the share.
expires_at	number	No	Unix timestamp (seconds) for auto-expiry. Pass null to never expire.

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

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

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

Allow the target (receiver) container owner to accept or reject an incoming share. A share is only mounted if 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

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

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

SDK usage

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

---

Deleting a share

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

Remove a storage share. The share ID is globally unique, so the source 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)

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