# Cua Volume

The versioned volume every Space and agent shares: files, history, grants, requests and audit.

> Agent discovery: use [the Cua documentation index](https://cua.ai/docs/llms.txt) to find related pages and their Markdown URLs.







Cua Volume methods on the `Spaces` registry. Access is checked by the runtime; pass a `DriveView` to see the drive as a persistent agent does. Grants and approvals ask the user for presence. Guide: [Cua Volume](</docs/spaces/guides/cua-volume>).

## Drive methods

Methods of [`Spaces`](</docs/cua-sdk/reference/spaces#spaces>).

### `Spaces.volume_ls`

`volume_ls`: a folder's immediate children (default the root).




**Python**



```python
async def volume_ls(self, path: Optional[str], view: Optional[DriveView]) -> DriveListing
```






**TypeScript**



```ts
volumeLs(path: string | undefined, view: DriveView | undefined, asyncOpts_?: { signal: AbortSignal }): Promise<DriveListing>
```






**Swift**



```swift
func volumeLs(path: String?, view: DriveView?) async throws -> DriveListing
```






**Kotlin**



```kotlin
@Throws(CuaException::class)
suspend fun volumeLs(path: String?, view: DriveView?): DriveListing
```






**Rust**



```rust
pub async fn volume_ls(&self, path: Option<String>, view: Option<DriveView>) -> Result<DriveListing, CuaError>
```






| Parameter | Type | Default |
| --- | --- | --- |
| `path` | `Option<String>` | required |
| `view` | [`Option<DriveView>`](#driveview-record) | required |

**Returns** [`DriveListing`](#drivelisting-record) · **Async** · **Raises** [`CuaError`](</docs/cua-sdk/reference/errors>)

### `Spaces.volume_read`

`volume_read`: a file (or one of its versions).




**Python**



```python
async def volume_read(self, path: str, version: Optional[str], view: Optional[DriveView]) -> DriveFile
```






**TypeScript**



```ts
volumeRead(path: string, version: string | undefined, view: DriveView | undefined, asyncOpts_?: { signal: AbortSignal }): Promise<DriveFile>
```






**Swift**



```swift
func volumeRead(path: String, version: String?, view: DriveView?) async throws -> DriveFile
```






**Kotlin**



```kotlin
@Throws(CuaException::class)
suspend fun volumeRead(path: String, version: String?, view: DriveView?): DriveFile
```






**Rust**



```rust
pub async fn volume_read(&self, path: String, version: Option<String>, view: Option<DriveView>) -> Result<DriveFile, CuaError>
```






| Parameter | Type | Default |
| --- | --- | --- |
| `path` | `String` | required |
| `version` | `Option<String>` | required |
| `view` | [`Option<DriveView>`](#driveview-record) | required |

**Returns** [`DriveFile`](#drivefile-record) · **Async** · **Raises** [`CuaError`](</docs/cua-sdk/reference/errors>)

### `Spaces.volume_write`

`volume_write`: a new version of a file. `if_etag` makes it a
compare-and-swap, `create_only` makes it create-only.




**Python**



```python
async def volume_write(self, path: str, content: bytes, if_etag: Optional[str], create_only: bool, view: Optional[DriveView]) -> DriveObject
```






**TypeScript**



```ts
volumeWrite(path: string, content: ArrayBuffer, ifEtag: string | undefined, createOnly: boolean, view: DriveView | undefined, asyncOpts_?: { signal: AbortSignal }): Promise<DriveObject>
```






**Swift**



```swift
func volumeWrite(path: String, content: Data, ifEtag: String?, createOnly: Bool, view: DriveView?) async throws -> DriveObject
```






**Kotlin**



```kotlin
@Throws(CuaException::class)
suspend fun volumeWrite(path: String, content: ByteArray, ifEtag: String?, createOnly: Boolean, view: DriveView?): DriveObject
```






**Rust**



```rust
pub async fn volume_write(&self, path: String, content: Vec<u8>, if_etag: Option<String>, create_only: bool, view: Option<DriveView>) -> Result<DriveObject, CuaError>
```






| Parameter | Type | Default |
| --- | --- | --- |
| `path` | `String` | required |
| `content` | `Vec<u8>` | required |
| `if_etag` | `Option<String>` | required |
| `create_only` | `bool` | required |
| `view` | [`Option<DriveView>`](#driveview-record) | required |

**Returns** [`DriveObject`](#driveobject-record) · **Async** · **Raises** [`CuaError`](</docs/cua-sdk/reference/errors>)

### `Spaces.volume_delete`

`volume_delete`: a delete marker (history stays).




**Python**



```python
async def volume_delete(self, path: str, if_etag: Optional[str], view: Optional[DriveView]) -> None
```






**TypeScript**



```ts
volumeDelete(path: string, ifEtag: string | undefined, view: DriveView | undefined, asyncOpts_?: { signal: AbortSignal }): Promise<void>
```






**Swift**



```swift
func volumeDelete(path: String, ifEtag: String?, view: DriveView?) async throws
```






**Kotlin**



```kotlin
@Throws(CuaException::class)
suspend fun volumeDelete(path: String, ifEtag: String?, view: DriveView?)
```






**Rust**



```rust
pub async fn volume_delete(&self, path: String, if_etag: Option<String>, view: Option<DriveView>) -> Result<(), CuaError>
```






| Parameter | Type | Default |
| --- | --- | --- |
| `path` | `String` | required |
| `if_etag` | `Option<String>` | required |
| `view` | [`Option<DriveView>`](#driveview-record) | required |

**Async** · **Raises** [`CuaError`](</docs/cua-sdk/reference/errors>)

### `Spaces.volume_history`

`volume_history`: a file's versions, newest first.




**Python**



```python
async def volume_history(self, path: str, view: Optional[DriveView]) -> List[DriveVersion]
```






**TypeScript**



```ts
volumeHistory(path: string, view: DriveView | undefined, asyncOpts_?: { signal: AbortSignal }): Promise<Array<DriveVersion>>
```






**Swift**



```swift
func volumeHistory(path: String, view: DriveView?) async throws -> [DriveVersion]
```






**Kotlin**



```kotlin
@Throws(CuaException::class)
suspend fun volumeHistory(path: String, view: DriveView?): List<DriveVersion>
```






**Rust**



```rust
pub async fn volume_history(&self, path: String, view: Option<DriveView>) -> Result<Vec<DriveVersion>, CuaError>
```






| Parameter | Type | Default |
| --- | --- | --- |
| `path` | `String` | required |
| `view` | [`Option<DriveView>`](#driveview-record) | required |

**Returns** [`Vec<DriveVersion>`](#driveversion-record) · **Async** · **Raises** [`CuaError`](</docs/cua-sdk/reference/errors>)

### `Spaces.volume_restore`

`volume_restore`: makes an old version current again.




**Python**



```python
async def volume_restore(self, path: str, version: str, view: Optional[DriveView]) -> DriveObject
```






**TypeScript**



```ts
volumeRestore(path: string, version: string, view: DriveView | undefined, asyncOpts_?: { signal: AbortSignal }): Promise<DriveObject>
```






**Swift**



```swift
func volumeRestore(path: String, version: String, view: DriveView?) async throws -> DriveObject
```






**Kotlin**



```kotlin
@Throws(CuaException::class)
suspend fun volumeRestore(path: String, version: String, view: DriveView?): DriveObject
```






**Rust**



```rust
pub async fn volume_restore(&self, path: String, version: String, view: Option<DriveView>) -> Result<DriveObject, CuaError>
```






| Parameter | Type | Default |
| --- | --- | --- |
| `path` | `String` | required |
| `version` | `String` | required |
| `view` | [`Option<DriveView>`](#driveview-record) | required |

**Returns** [`DriveObject`](#driveobject-record) · **Async** · **Raises** [`CuaError`](</docs/cua-sdk/reference/errors>)

### `Spaces.volume_grant`

`volume_grant`: widens `principal`'s access (`agent:<name>` or
`space:<id>`, mode `r` or `rw`). The user confirms with presence.




**Python**



```python
async def volume_grant(self, principal: str, prefix: str, mode: str, expires_in_secs: Optional[int], note: Optional[str]) -> DriveGrant
```






**TypeScript**



```ts
volumeGrant(principal: string, prefix: string, mode: string, expiresInSecs: bigint | undefined, note: string | undefined, asyncOpts_?: { signal: AbortSignal }): Promise<DriveGrant>
```






**Swift**



```swift
func volumeGrant(principal: String, prefix: String, mode: String, expiresInSecs: UInt64?, note: String?) async throws -> DriveGrant
```






**Kotlin**



```kotlin
@Throws(CuaException::class)
suspend fun volumeGrant(principal: String, prefix: String, mode: String, expiresInSecs: ULong?, note: String?): DriveGrant
```






**Rust**



```rust
pub async fn volume_grant(&self, principal: String, prefix: String, mode: String, expires_in_secs: Option<u64>, note: Option<String>) -> Result<DriveGrant, CuaError>
```






| Parameter | Type | Default |
| --- | --- | --- |
| `principal` | `String` | required |
| `prefix` | `String` | required |
| `mode` | `String` | required |
| `expires_in_secs` | `Option<u64>` | required |
| `note` | `Option<String>` | required |

**Returns** [`DriveGrant`](#drivegrant-record) · **Async** · **Raises** [`CuaError`](</docs/cua-sdk/reference/errors>)

### `Spaces.volume_revoke`

`volume_revoke`.




**Python**



```python
async def volume_revoke(self, grant_id: str) -> DriveGrant
```






**TypeScript**



```ts
volumeRevoke(grantId: string, asyncOpts_?: { signal: AbortSignal }): Promise<DriveGrant>
```






**Swift**



```swift
func volumeRevoke(grantId: String) async throws -> DriveGrant
```






**Kotlin**



```kotlin
@Throws(CuaException::class)
suspend fun volumeRevoke(grantId: String): DriveGrant
```






**Rust**



```rust
pub async fn volume_revoke(&self, grant_id: String) -> Result<DriveGrant, CuaError>
```






| Parameter | Type | Default |
| --- | --- | --- |
| `grant_id` | `String` | required |

**Returns** [`DriveGrant`](#drivegrant-record) · **Async** · **Raises** [`CuaError`](</docs/cua-sdk/reference/errors>)

### `Spaces.volume_grants`

`volume_grants`: live grants (every grant with `all`).




**Python**



```python
async def volume_grants(self, all: bool) -> List[DriveGrant]
```






**TypeScript**



```ts
volumeGrants(all: boolean, asyncOpts_?: { signal: AbortSignal }): Promise<Array<DriveGrant>>
```






**Swift**



```swift
func volumeGrants(all: Bool) async throws -> [DriveGrant]
```






**Kotlin**



```kotlin
@Throws(CuaException::class)
suspend fun volumeGrants(all: Boolean): List<DriveGrant>
```






**Rust**



```rust
pub async fn volume_grants(&self, all: bool) -> Result<Vec<DriveGrant>, CuaError>
```






| Parameter | Type | Default |
| --- | --- | --- |
| `all` | `bool` | required |

**Returns** [`Vec<DriveGrant>`](#drivegrant-record) · **Async** · **Raises** [`CuaError`](</docs/cua-sdk/reference/errors>)

### `Spaces.volume_request_access`

`volume_request_access`: `agent` asks the user for more access.




**Python**



```python
async def volume_request_access(self, agent: str, prefix: str, mode: str, reason: Optional[str], in_space: Optional[str]) -> DriveAccessRequest
```






**TypeScript**



```ts
volumeRequestAccess(agent: string, prefix: string, mode: string, reason: string | undefined, inSpace: string | undefined, asyncOpts_?: { signal: AbortSignal }): Promise<DriveAccessRequest>
```






**Swift**



```swift
func volumeRequestAccess(agent: String, prefix: String, mode: String, reason: String?, inSpace: String?) async throws -> DriveAccessRequest
```






**Kotlin**



```kotlin
@Throws(CuaException::class)
suspend fun volumeRequestAccess(agent: String, prefix: String, mode: String, reason: String?, inSpace: String?): DriveAccessRequest
```






**Rust**



```rust
pub async fn volume_request_access(&self, agent: String, prefix: String, mode: String, reason: Option<String>, in_space: Option<String>) -> Result<DriveAccessRequest, CuaError>
```






| Parameter | Type | Default |
| --- | --- | --- |
| `agent` | `String` | required |
| `prefix` | `String` | required |
| `mode` | `String` | required |
| `reason` | `Option<String>` | required |
| `in_space` | `Option<String>` | required |

**Returns** [`DriveAccessRequest`](#driveaccessrequest-record) · **Async** · **Raises** [`CuaError`](</docs/cua-sdk/reference/errors>)

### `Spaces.volume_requests`

`volume_requests`: requests waiting for the user.




**Python**



```python
async def volume_requests(self) -> List[DriveAccessRequest]
```






**TypeScript**



```ts
volumeRequests(asyncOpts_?: { signal: AbortSignal }): Promise<Array<DriveAccessRequest>>
```






**Swift**



```swift
func volumeRequests() async throws -> [DriveAccessRequest]
```






**Kotlin**



```kotlin
@Throws(CuaException::class)
suspend fun volumeRequests(): List<DriveAccessRequest>
```






**Rust**



```rust
pub async fn volume_requests(&self) -> Result<Vec<DriveAccessRequest>, CuaError>
```






**Returns** [`Vec<DriveAccessRequest>`](#driveaccessrequest-record) · **Async** · **Raises** [`CuaError`](</docs/cua-sdk/reference/errors>)

### `Spaces.volume_approve`

`volume_approve`: the request becomes a grant (with presence).




**Python**



```python
async def volume_approve(self, request_id: str, expires_in_secs: Optional[int]) -> DriveGrant
```






**TypeScript**



```ts
volumeApprove(requestId: string, expiresInSecs: bigint | undefined, asyncOpts_?: { signal: AbortSignal }): Promise<DriveGrant>
```






**Swift**



```swift
func volumeApprove(requestId: String, expiresInSecs: UInt64?) async throws -> DriveGrant
```






**Kotlin**



```kotlin
@Throws(CuaException::class)
suspend fun volumeApprove(requestId: String, expiresInSecs: ULong?): DriveGrant
```






**Rust**



```rust
pub async fn volume_approve(&self, request_id: String, expires_in_secs: Option<u64>) -> Result<DriveGrant, CuaError>
```






| Parameter | Type | Default |
| --- | --- | --- |
| `request_id` | `String` | required |
| `expires_in_secs` | `Option<u64>` | required |

**Returns** [`DriveGrant`](#drivegrant-record) · **Async** · **Raises** [`CuaError`](</docs/cua-sdk/reference/errors>)

### `Spaces.volume_deny`

`volume_deny`.




**Python**



```python
async def volume_deny(self, request_id: str) -> None
```






**TypeScript**



```ts
volumeDeny(requestId: string, asyncOpts_?: { signal: AbortSignal }): Promise<void>
```






**Swift**



```swift
func volumeDeny(requestId: String) async throws
```






**Kotlin**



```kotlin
@Throws(CuaException::class)
suspend fun volumeDeny(requestId: String)
```






**Rust**



```rust
pub async fn volume_deny(&self, request_id: String) -> Result<(), CuaError>
```






| Parameter | Type | Default |
| --- | --- | --- |
| `request_id` | `String` | required |

**Async** · **Raises** [`CuaError`](</docs/cua-sdk/reference/errors>)

### `Spaces.volume_audit`

`volume_audit`: the newest events (default 50) and whether the log
verified.




**Python**



```python
async def volume_audit(self, limit: Optional[int]) -> DriveAudit
```






**TypeScript**



```ts
volumeAudit(limit: number | undefined, asyncOpts_?: { signal: AbortSignal }): Promise<DriveAudit>
```






**Swift**



```swift
func volumeAudit(limit: UInt32?) async throws -> DriveAudit
```






**Kotlin**



```kotlin
@Throws(CuaException::class)
suspend fun volumeAudit(limit: UInt?): DriveAudit
```






**Rust**



```rust
pub async fn volume_audit(&self, limit: Option<u32>) -> Result<DriveAudit, CuaError>
```






| Parameter | Type | Default |
| --- | --- | --- |
| `limit` | `Option<u32>` | required |

**Returns** [`DriveAudit`](#driveaudit-record) · **Async** · **Raises** [`CuaError`](</docs/cua-sdk/reference/errors>)

## `DriveView` record

Whose view of the drive a call takes: the user (the default, the whole
drive) or a persistent agent in a Space. It only ever narrows.

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `as_agent` / `asAgent` | `Option<String>` | `None` | A persistent agent's name (`ada`). |
| `in_space` / `inSpace` | `Option<String>` | `None` | The Space id the agent is in (`local:work`). |

## `DriveListing` record

A folder's listing.

Returned by [`Spaces.volume_ls`](#spacesvolume_ls).

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `path` | `String` |  |  |
| `principal` | `String` |  | `user` or `agent:<name>`. |
| `entries` | [`Vec<DriveEntry>`](#driveentry-record) |  |  |

## `DriveEntry` record

One row of a drive listing.

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `path` | `String` |  | Key (folders end in `/`). |
| `name` | `String` |  |  |
| `folder` | `bool` |  |  |
| `size` | `u64` |  |  |
| `modified_ms` / `modifiedMs` | `u64` |  |  |
| `etag` | `String` |  |  |
| `mode` | `String` |  | `r` or `rw`: what this view may do there. |
| `sync` | [`Option<DriveFileSync>`](#drivefilesync-record) |  | A file's sync state, when it has something to say (uploading, conflicted, or last written by another device). |

## `DriveFile` record

A file's content and version.

Returned by [`Spaces.volume_read`](#spacesvolume_read).

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `path` | `String` |  |  |
| `size` | `u64` |  |  |
| `etag` | `String` |  |  |
| `version` | `String` |  |  |
| `modified_ms` / `modifiedMs` | `u64` |  |  |
| `content` | `Vec<u8>` |  |  |
| `sync` | [`Option<DriveFileSync>`](#drivefilesync-record) |  | Its sync state, while the drive's services run. |

## `DriveObject` record

A written version.

Returned by [`Spaces.volume_restore`](#spacesvolume_restore), [`Spaces.volume_write`](#spacesvolume_write).

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `key` | `String` |  |  |
| `size` | `u64` |  |  |
| `etag` | `String` |  |  |
| `version` | `String` |  |  |
| `modified_ms` / `modifiedMs` | `u64` |  |  |

## `DriveVersion` record

One version in a file's history.

Returned by [`Spaces.volume_history`](#spacesvolume_history).

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `version` | `String` |  |  |
| `size` | `u64` |  |  |
| `modified_ms` / `modifiedMs` | `u64` |  |  |
| `deleted` | `bool` |  |  |
| `latest` | `bool` |  |  |

## `DriveGrant` record

A widening of an agent's or a Space's access.

Returned by [`Spaces.volume_approve`](#spacesvolume_approve), [`Spaces.volume_grant`](#spacesvolume_grant), [`Spaces.volume_grants`](#spacesvolume_grants), [`Spaces.volume_revoke`](#spacesvolume_revoke).

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `String` |  |  |
| `principal` | `String` |  |  |
| `prefix` | `String` |  |  |
| `mode` | `String` |  | `r` or `rw`. |
| `created_ms` / `createdMs` | `u64` |  |  |
| `expires_ms` / `expiresMs` | `Option<u64>` |  |  |
| `revoked` | `bool` |  |  |
| `note` | `String` |  |  |

## `DriveAccessRequest` record

An agent's request for more access, waiting for the user.

Returned by [`Spaces.volume_request_access`](#spacesvolume_request_access), [`Spaces.volume_requests`](#spacesvolume_requests).

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `String` |  |  |
| `principal` | `String` |  |  |
| `prefix` | `String` |  |  |
| `mode` | `String` |  |  |
| `reason` | `String` |  |  |
| `created_ms` / `createdMs` | `u64` |  |  |

## `DriveAudit` record

The newest audit events and whether the hash chain verified.

Returned by [`Spaces.volume_audit`](#spacesvolume_audit).

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `events` | [`Vec<DriveAuditEvent>`](#driveauditevent-record) |  |  |
| `verified` | `bool` |  |  |
| `error` | `Option<String>` |  |  |

## `DriveAuditEvent` record

One audit event.

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `seq` | `u64` |  |  |
| `ts_ms` / `tsMs` | `u64` |  |  |
| `principal` | `String` |  |  |
| `action` | `String` |  |  |
| `path` | `String` |  |  |
| `detail` | `String` |  |  |

## `DriveFileSync` record

One file's sync state.

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `state` | `String` |  | `synced`, `pending_upload` (not yet in storage: other devices do not see it), `conflict` (a write lost to a later one, kept at `conflict_path`) or `conflict_copy` (the kept copy of a losing write). |
| `written_by` / `writtenBy` | `Option<String>` |  | The device that last wrote it, when another one did. |
| `conflict_path` / `conflictPath` | `Option<String>` |  |  |