# Storage Shares

**Page:** api/storage-shares

[Download Raw Markdown](./api/storage-shares.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



## 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



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


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


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


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



#### SDK Usage

```ts
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



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


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



#### SDK Usage

```ts
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 |

```json
{
  "mount": true
}
```

#### Response



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


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


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


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


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



#### SDK Usage

```ts
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



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


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


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



#### SDK Usage

```ts
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



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


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



#### SDK Usage

```ts
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



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


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


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


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



#### SDK Usage

```ts
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).


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 |

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

#### Response



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


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


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


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


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


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


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

```ts
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) |

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

#### Response



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


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


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


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


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



#### SDK Usage

```ts
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



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


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


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


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



#### SDK Usage

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