# Storage Volumes

Every registered storage volumes instance operation, with source-derived inputs, outputs, access policy, and errors.

Source: https://docs.minds.sh/docs/api/instance/storage-volumes



This reference covers **5 HTTP operations** registered by the Akasha daemon. Call these paths on your instance base URL. See [authentication](/docs/api/instance/authentication), [errors](/docs/api/instance/errors), and [coverage](/docs/api/instance/coverage) before integrating.

| Method   | Path                         | Operation                                                |
| -------- | ---------------------------- | -------------------------------------------------------- |
| `GET`    | `/v1/storage/volumes`        | [Storage volume list](#get-v1-storage-volumes)           |
| `POST`   | `/v1/storage/volumes`        | [Storage volume create](#post-v1-storage-volumes)        |
| `POST`   | `/v1/storage/volumes/attach` | [Storage volume attach](#post-v1-storage-volumes-attach) |
| `POST`   | `/v1/storage/volumes/detach` | [Storage volume detach](#post-v1-storage-volumes-detach) |
| `DELETE` | `/v1/storage/volumes/:id`    | [Storage volume delete](#delete-v1-storage-volumes-id)   |

<a id="get-v1-storage-volumes" />

## GET `/v1/storage/volumes` [#get-v1storagevolumes]

Storage volume list

| Availability         | Source contract                                                  |
| -------------------- | ---------------------------------------------------------------- |
| Registration         | `config.enable_kv`                                               |
| Runtime service      | No prefix-level service check; handler dependencies still apply. |
| Handler dependencies | See handler source and return expressions.                       |

**Access:** Daemon authentication and capability namespace authority; memory-domain permissions apply where mapped.

### Request [#request]

No typed JSON, query, or path extractor is declared in the handler signature. Headers or request objects may still be consumed; the signature below is authoritative.

### Response [#response]

**Declared return:** `Result<impl IntoResponse, DaemonError>`

The following are the exact JSON construction expressions in the handler. Values such as `rows`, `result`, and delegated types are runtime values, not literal example payloads.

```rust
records
```

### Errors and validation [#errors-and-validation]

Directly referenced error variants: none in the handler body. Middleware and delegated services can return additional errors described in the shared error reference.

<Accordions>
  <Accordion title="Inspect implementation">
    This exact source excerpt includes validation, defaults, delegated calls, and response assembly.

    ```rust
    async fn storage_volume_list(
        State(state): State<AppState>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        let registry = state.volume_registry()?;
        let records = registry.list_volumes().await;
        Ok(Json(records))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:3187`. Registration: `akasha-daemon/src/main.rs:4619`.

<a id="post-v1-storage-volumes" />

## POST `/v1/storage/volumes` [#post-v1storagevolumes]

Storage volume create

| Availability         | Source contract                                                  |
| -------------------- | ---------------------------------------------------------------- |
| Registration         | `config.enable_kv`                                               |
| Runtime service      | No prefix-level service check; handler dependencies still apply. |
| Handler dependencies | See handler source and return expressions.                       |

**Access:** Daemon authentication and capability namespace authority; memory-domain permissions apply where mapped.

### Request [#request-1]

**Json** — `VolumeCreateRequest`

| Field             | Rust type        | Required on input         | Notes            |
| ----------------- | ---------------- | ------------------------- | ---------------- |
| `name`            | `String`         | Yes                       |                  |
| `purpose`         | `String`         | Yes                       |                  |
| `description`     | `Option<String>` | No; optional or defaulted | Serde: `default` |
| `kms_key_version` | `Option<u64>`    | No; optional or defaulted | Serde: `default` |
| `provider`        | `VolumeProvider` | Yes                       |                  |

```rust
struct VolumeCreateRequest {
    name: String,
    purpose: String,
    #[serde(default)]
    description: Option<String>,
    #[serde(default)]
    kms_key_version: Option<u64>,
    provider: VolumeProvider,
}
```

### Response [#response-1]

**Declared return:** `Result<impl IntoResponse, DaemonError>`

The following are the exact JSON construction expressions in the handler. Values such as `rows`, `result`, and delegated types are runtime values, not literal example payloads.

```rust
record
```

### Errors and validation [#errors-and-validation-1]

Directly referenced error variants: `from`. Middleware and delegated services can return additional errors described in the shared error reference.

<Accordions>
  <Accordion title="Inspect implementation">
    This exact source excerpt includes validation, defaults, delegated calls, and response assembly.

    ```rust
    async fn storage_volume_create(
        State(state): State<AppState>,
        Json(req): Json<VolumeCreateRequest>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        let registry = state.volume_registry()?;
        let new_volume = NewVolume {
            name: req.name,
            description: req.description,
            purpose: req.purpose,
            provider: req.provider,
            kms_key_version: req.kms_key_version,
        };
        let record = registry
            .create_volume(new_volume)
            .await
            .map_err(DaemonError::from)?;
        Ok(Json(record))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:3167`. Registration: `akasha-daemon/src/main.rs:4619`.

<a id="post-v1-storage-volumes-attach" />

## POST `/v1/storage/volumes/attach` [#post-v1storagevolumesattach]

Storage volume attach

| Availability         | Source contract                                                  |
| -------------------- | ---------------------------------------------------------------- |
| Registration         | `config.enable_kv`                                               |
| Runtime service      | No prefix-level service check; handler dependencies still apply. |
| Handler dependencies | See handler source and return expressions.                       |

**Access:** Daemon authentication and capability namespace authority; memory-domain permissions apply where mapped.

### Request [#request-2]

**Json** — `VolumeAttachRequest`

| Field       | Rust type        | Required on input         | Notes            |
| ----------- | ---------------- | ------------------------- | ---------------- |
| `volume_id` | `String`         | Yes                       |                  |
| `namespace` | `String`         | Yes                       |                  |
| `purpose`   | `Option<String>` | No; optional or defaulted | Serde: `default` |

```rust
struct VolumeAttachRequest {
    volume_id: String,
    namespace: String,
    #[serde(default)]
    purpose: Option<String>,
}
```

### Response [#response-2]

**Declared return:** `Result<impl IntoResponse, DaemonError>`

The following are the exact JSON construction expressions in the handler. Values such as `rows`, `result`, and delegated types are runtime values, not literal example payloads.

```rust
record
```

### Errors and validation [#errors-and-validation-2]

Directly referenced error variants: `from`. Middleware and delegated services can return additional errors described in the shared error reference.

<Accordions>
  <Accordion title="Inspect implementation">
    This exact source excerpt includes validation, defaults, delegated calls, and response assembly.

    ```rust
    async fn storage_volume_attach(
        State(state): State<AppState>,
        Json(req): Json<VolumeAttachRequest>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        let registry = state.volume_registry()?;
        let namespace_hex = req.namespace.trim().to_lowercase();
        let _ = decode_namespace_hex(&namespace_hex)?;
        let record = registry
            .attach_volume(&req.volume_id, namespace_hex.clone(), req.purpose.clone())
            .await
            .map_err(DaemonError::from)?;

        if let Some(runtime) = state.volume_runtime() {
            match runtime.attach_volume(record.clone()).await {
                Ok(binding) => {
                    if binding.purpose.to_lowercase() == PURPOSE_KV {
                        state
                            .invalidate_namespace_binding(&binding.namespace_hex)
                            .await;
                    }
                }
                Err(err) => {
                    warn!(
                        volume_id = %record.id,
                        error = %err,
                        "volume runtime attach failed, rolling back registry entry"
                    );
                    let _ = state
                        .volume_registry()?
                        .detach_volume(&record.id)
                        .await
                        .map_err(DaemonError::from)?;
                    return Err(DaemonError::from(err));
                }
            }
        }

        Ok(Json(record))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:3196`. Registration: `akasha-daemon/src/main.rs:4623`.

<a id="post-v1-storage-volumes-detach" />

## POST `/v1/storage/volumes/detach` [#post-v1storagevolumesdetach]

Storage volume detach

| Availability         | Source contract                                                  |
| -------------------- | ---------------------------------------------------------------- |
| Registration         | `config.enable_kv`                                               |
| Runtime service      | No prefix-level service check; handler dependencies still apply. |
| Handler dependencies | See handler source and return expressions.                       |

**Access:** Daemon authentication and capability namespace authority; memory-domain permissions apply where mapped.

### Request [#request-3]

**Json** — `VolumeDetachRequest`

| Field       | Rust type | Required on input | Notes |
| ----------- | --------- | ----------------- | ----- |
| `volume_id` | `String`  | Yes               |       |

```rust
struct VolumeDetachRequest {
    volume_id: String,
}
```

### Response [#response-3]

**Declared return:** `Result<impl IntoResponse, DaemonError>`

The following are the exact JSON construction expressions in the handler. Values such as `rows`, `result`, and delegated types are runtime values, not literal example payloads.

```rust
record
```

### Errors and validation [#errors-and-validation-3]

Directly referenced error variants: `from`. Middleware and delegated services can return additional errors described in the shared error reference.

<Accordions>
  <Accordion title="Inspect implementation">
    This exact source excerpt includes validation, defaults, delegated calls, and response assembly.

    ```rust
    async fn storage_volume_detach(
        State(state): State<AppState>,
        Json(req): Json<VolumeDetachRequest>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        let registry = state.volume_registry()?;
        let record = registry
            .detach_volume(&req.volume_id)
            .await
            .map_err(DaemonError::from)?;

        if let Some(runtime) = state.volume_runtime()
            && let Some(binding) = runtime
                .detach_by_id(&req.volume_id)
                .await
                .map_err(DaemonError::from)?
            && binding.purpose.to_lowercase() == PURPOSE_KV
            && !binding.namespace_hex.is_empty()
        {
            state
                .invalidate_namespace_binding(&binding.namespace_hex)
                .await;
        }

        Ok(Json(record))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:3237`. Registration: `akasha-daemon/src/main.rs:4624`.

<a id="delete-v1-storage-volumes-id" />

## DELETE `/v1/storage/volumes/:id` [#delete-v1storagevolumesid]

Storage volume delete

| Availability         | Source contract                                                  |
| -------------------- | ---------------------------------------------------------------- |
| Registration         | `config.enable_kv`                                               |
| Runtime service      | No prefix-level service check; handler dependencies still apply. |
| Handler dependencies | See handler source and return expressions.                       |

**Access:** Daemon authentication and capability namespace authority; memory-domain permissions apply where mapped.

### Request [#request-4]

**Path** — `String`

```json
{
  "type": "string"
}
```

### Response [#response-4]

**Declared return:** `Result<impl IntoResponse, DaemonError>`

The following are the exact JSON construction expressions in the handler. Values such as `rows`, `result`, and delegated types are runtime values, not literal example payloads.

```rust
record
```

### Errors and validation [#errors-and-validation-4]

Directly referenced error variants: `from`. Middleware and delegated services can return additional errors described in the shared error reference.

<Accordions>
  <Accordion title="Inspect implementation">
    This exact source excerpt includes validation, defaults, delegated calls, and response assembly.

    ```rust
    async fn storage_volume_delete(
        State(state): State<AppState>,
        Path(volume_id): Path<String>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        let registry = state.volume_registry()?;
        let record = registry
            .delete_volume(&volume_id)
            .await
            .map_err(DaemonError::from)?;
        Ok(Json(record))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:3264`. Registration: `akasha-daemon/src/main.rs:4625`.