# Model Management

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

Source: https://docs.minds.sh/docs/api/instance/model-management



This reference covers **8 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/models`                  | [Models list](#get-v1-models)                   |
| `POST`   | `/v1/models/load`             | [Models load](#post-v1-models-load)             |
| `POST`   | `/v1/models/download`         | [Models download](#post-v1-models-download)     |
| `GET`    | `/v1/models/memory`           | [Models memory usage](#get-v1-models-memory)    |
| `GET`    | `/v1/models/health`           | [Models health](#get-v1-models-health)          |
| `GET`    | `/v1/models/:model_id`        | [Models get one](#get-v1-models-model-id)       |
| `DELETE` | `/v1/models/:model_id`        | [Models delete](#delete-v1-models-model-id)     |
| `GET`    | `/v1/models/:model_id/status` | [Models status](#get-v1-models-model-id-status) |

<a id="get-v1-models" />

## GET `/v1/models` [#get-v1models]

GET /v1/models - List all models with their statuses

| Availability         | Source contract                                                  |
| -------------------- | ---------------------------------------------------------------- |
| Registration         | `always registered`                                              |
| 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<Json<ModelsListResponse>, 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
ModelsListResponse {
        models: model_infos,
        total,
        memory_used_bytes: memory_used,
        memory_budget_bytes: memory_budget,
    }
```

### 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 models_list(
        State(state): State<AppState>,
    ) -> Result<Json<ModelsListResponse>, DaemonError> {
        state.record_http_request();
        let manager = require_model_manager(&state)?;

        let states = manager.get_all_states().await;
        let memory_used = manager.memory_usage().await;
        let memory_budget = manager.memory_budget();

        let mut model_infos = Vec::with_capacity(states.len());
        for model_state in &states {
            if let Some(spec) = manager.get_spec(&model_state.id) {
                model_infos.push(build_model_info(spec, model_state));
            }
        }

        let total = model_infos.len();
        Ok(Json(ModelsListResponse {
            models: model_infos,
            total,
            memory_used_bytes: memory_used,
            memory_budget_bytes: memory_budget,
        }))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:4877`. Registration: `akasha-daemon/src/main.rs:4742`.

<a id="post-v1-models-load" />

## POST `/v1/models/load` [#post-v1modelsload]

POST /v1/models/load - Load a model into memory

| Availability         | Source contract                                                  |
| -------------------- | ---------------------------------------------------------------- |
| Registration         | `always registered`                                              |
| 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** — `ModelLoadRequest`

| Field            | Rust type | Required on input         | Notes            |
| ---------------- | --------- | ------------------------- | ---------------- |
| `model_id`       | `String`  | Yes                       |                  |
| `force_download` | `bool`    | No; optional or defaulted | Serde: `default` |

```rust
struct ModelLoadRequest {
    model_id: String,
    #[serde(default)]
    force_download: bool,
}
```

### Response [#response-1]

**Declared return:** `Result<Json<ModelOpResponse>, 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
ModelOpResponse {
            success: true,
            model_id: req.model_id.clone(),
            status: "loaded".to_string(),
            message: format!(
                "Model '{}' loaded ({} RAM, path: {})",
                req.model_id,
                models::progress::format_bytes(handle.memory_bytes),
                handle.path.display()
            ),
        }
```

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

Directly referenced error variants: `Internal`, `InvalidRequest`. 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 models_load(
        State(state): State<AppState>,
        Json(req): Json<ModelLoadRequest>,
    ) -> Result<Json<ModelOpResponse>, DaemonError> {
        state.record_http_request();
        let manager = require_model_manager(&state)?;

        // If force download requested, download first
        if req.force_download {
            let opts = models::DownloadOptions {
                force: true,
                ..Default::default()
            };
            manager
                .ensure_model_available(&req.model_id, &opts)
                .await
                .map_err(|e| DaemonError::Internal(format!("model download failed: {}", e)))?;
        }

        match manager.load_model(&req.model_id).await {
            Ok(handle) => Ok(Json(ModelOpResponse {
                success: true,
                model_id: req.model_id.clone(),
                status: "loaded".to_string(),
                message: format!(
                    "Model '{}' loaded ({} RAM, path: {})",
                    req.model_id,
                    models::progress::format_bytes(handle.memory_bytes),
                    handle.path.display()
                ),
            })),
            Err(e) => Err(match e {
                models::ModelError::NotFound(ref id) => {
                    DaemonError::InvalidRequest(format!("model '{}' not found in registry", id))
                }
                models::ModelError::AlreadyLoading(ref id) => {
                    DaemonError::InvalidRequest(format!("model '{}' is already loading", id))
                }
                models::ModelError::InsufficientMemory { needed, available } => {
                    DaemonError::InvalidRequest(format!(
                        "insufficient memory: need {}, have {}",
                        models::progress::format_bytes(needed),
                        models::progress::format_bytes(available)
                    ))
                }
                models::ModelError::InsufficientDiskSpace { needed, available } => {
                    DaemonError::InvalidRequest(format!(
                        "insufficient disk space: need {}, have {}",
                        models::progress::format_bytes(needed),
                        models::progress::format_bytes(available)
                    ))
                }
                _ => DaemonError::Internal(format!("model load failed: {}", e)),
            }),
        }
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:4960`. Registration: `akasha-daemon/src/main.rs:4743`.

<a id="post-v1-models-download" />

## POST `/v1/models/download` [#post-v1modelsdownload]

POST /v1/models/download - Download a model without loading it

| Availability         | Source contract                                                  |
| -------------------- | ---------------------------------------------------------------- |
| Registration         | `always registered`                                              |
| 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** — `ModelDownloadRequest`

| Field         | Rust type | Required on input         | Notes                                    |
| ------------- | --------- | ------------------------- | ---------------------------------------- |
| `model_id`    | `String`  | Yes                       |                                          |
| `force`       | `bool`    | No; optional or defaulted | Serde: `default`                         |
| `verify_hash` | `bool`    | No; optional or defaulted | Serde: `default = "default_verify_hash"` |

```rust
struct ModelDownloadRequest {
    model_id: String,
    #[serde(default)]
    force: bool,
    #[serde(default = "default_verify_hash")]
    verify_hash: bool,
}
```

### Response [#response-2]

**Declared return:** `Result<Json<ModelOpResponse>, 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
ModelOpResponse {
            success: true,
            model_id: req.model_id.clone(),
            status: "downloaded".to_string(),
            message: format!("Model '{}' downloaded to {}", req.model_id, path.display()),
        }
```

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

Directly referenced error variants: `Internal`, `InvalidRequest`. 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 models_download(
        State(state): State<AppState>,
        Json(req): Json<ModelDownloadRequest>,
    ) -> Result<Json<ModelOpResponse>, DaemonError> {
        state.record_http_request();
        let manager = require_model_manager(&state)?;

        let opts = models::DownloadOptions {
            force: req.force,
            verify_hash: req.verify_hash,
            ..Default::default()
        };

        match manager.ensure_model_available(&req.model_id, &opts).await {
            Ok(path) => Ok(Json(ModelOpResponse {
                success: true,
                model_id: req.model_id.clone(),
                status: "downloaded".to_string(),
                message: format!("Model '{}' downloaded to {}", req.model_id, path.display()),
            })),
            Err(e) => Err(match e {
                models::ModelError::NotFound(ref id) => {
                    DaemonError::InvalidRequest(format!("model '{}' not found in registry", id))
                }
                _ => DaemonError::Internal(format!("model download failed: {}", e)),
            }),
        }
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:5018`. Registration: `akasha-daemon/src/main.rs:4744`.

<a id="get-v1-models-memory" />

## GET `/v1/models/memory` [#get-v1modelsmemory]

GET /v1/models/memory - Get memory usage breakdown

| Availability         | Source contract                                                  |
| -------------------- | ---------------------------------------------------------------- |
| Registration         | `always registered`                                              |
| 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]

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-3]

**Declared return:** `Result<Json<ModelsMemoryResponse>, 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
ModelsMemoryResponse {
        memory_used_bytes: memory_used,
        memory_budget_bytes: memory_budget,
        utilization_percent: utilization,
        loaded_models,
    }
```

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

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 models_memory_usage(
        State(state): State<AppState>,
    ) -> Result<Json<ModelsMemoryResponse>, DaemonError> {
        state.record_http_request();
        let manager = require_model_manager(&state)?;

        let memory_used = manager.memory_usage().await;
        let memory_budget = manager.memory_budget();
        let utilization = if memory_budget > 0 {
            (memory_used as f64 / memory_budget as f64) * 100.0
        } else {
            0.0
        };

        let all_states = manager.get_all_states().await;
        let mut loaded_models = Vec::new();

        for model_state in &all_states {
            if let Some(handle) = manager.get_handle(&model_state.id).await {
                loaded_models.push(LoadedModelInfo {
                    id: model_state.id.clone(),
                    name: model_state.name.clone(),
                    memory_bytes: handle.memory_bytes,
                    uptime_seconds: handle.uptime().as_secs(),
                });
            }
        }

        Ok(Json(ModelsMemoryResponse {
            memory_used_bytes: memory_used,
            memory_budget_bytes: memory_budget,
            utilization_percent: utilization,
            loaded_models,
        }))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:5077`. Registration: `akasha-daemon/src/main.rs:4745`.

<a id="get-v1-models-health" />

## GET `/v1/models/health` [#get-v1modelshealth]

GET /v1/models/health - Health check for model subsystem

| Availability         | Source contract                                                  |
| -------------------- | ---------------------------------------------------------------- |
| Registration         | `always registered`                                              |
| 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]

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-4]

**Declared return:** `Result<Json<Value>, 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
json!({
        "status": status,
        "total_models": all_states.len(),
        "loaded": loaded_count,
        "downloaded": downloaded_count,
        "failed": failed_count,
        "memory_used_bytes": memory_used,
        "memory_budget_bytes": memory_budget,
        "core_models": core_model_ids,
        "extended_models": extended_model_ids,
        "core_total_size_bytes": registry.core_size_bytes(),
        "core_total_ram_bytes": registry.core_ram_bytes(),
        "all_total_size_bytes": registry.total_size_bytes(),
    })
```

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

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 models_health(State(state): State<AppState>) -> Result<Json<Value>, DaemonError> {
        state.record_http_request();
        let manager = require_model_manager(&state)?;

        let all_states = manager.get_all_states().await;
        let loaded_count = all_states
            .iter()
            .filter(|s| matches!(s.status, models::ModelStatus::Loaded))
            .count();
        let downloaded_count = all_states
            .iter()
            .filter(|s| {
                matches!(
                    s.status,
                    models::ModelStatus::Downloaded | models::ModelStatus::Loaded
                )
            })
            .count();
        let failed_count = all_states
            .iter()
            .filter(|s| matches!(s.status, models::ModelStatus::Failed))
            .count();

        let memory_used = manager.memory_usage().await;
        let memory_budget = manager.memory_budget();

        let registry = manager.registry();
        let core_model_ids: Vec<&str> = models::CORE_MODELS.to_vec();
        let extended_model_ids: Vec<&str> = models::EXTENDED_MODELS.to_vec();

        let status = if failed_count > 0 { "degraded" } else { "ok" };

        Ok(Json(json!({
            "status": status,
            "total_models": all_states.len(),
            "loaded": loaded_count,
            "downloaded": downloaded_count,
            "failed": failed_count,
            "memory_used_bytes": memory_used,
            "memory_budget_bytes": memory_budget,
            "core_models": core_model_ids,
            "extended_models": extended_model_ids,
            "core_total_size_bytes": registry.core_size_bytes(),
            "core_total_ram_bytes": registry.core_ram_bytes(),
            "all_total_size_bytes": registry.total_size_bytes(),
        })))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:5114`. Registration: `akasha-daemon/src/main.rs:4746`.

<a id="get-v1-models-model-id" />

## GET `/v1/models/:model_id` [#get-v1modelsmodel_id]

GET /v1/models/:model\_id - Get single model details

| Availability         | Source contract                                                  |
| -------------------- | ---------------------------------------------------------------- |
| Registration         | `always registered`                                              |
| 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-5]

**Path** — `String`

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

### Response [#response-5]

**Declared return:** `Result<Json<ModelInfoResponse>, 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
build_model_info(spec, &model_state)
```

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

Directly referenced error variants: `InvalidRequest`. 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 models_get_one(
        State(state): State<AppState>,
        Path(model_id): Path<String>,
    ) -> Result<Json<ModelInfoResponse>, DaemonError> {
        state.record_http_request();
        let manager = require_model_manager(&state)?;

        let model_state = manager
            .get_state(&model_id)
            .await
            .ok_or_else(|| DaemonError::InvalidRequest(format!("model '{}' not found", model_id)))?;

        let spec = manager.get_spec(&model_id).ok_or_else(|| {
            DaemonError::InvalidRequest(format!("model '{}' not in registry", model_id))
        })?;

        Ok(Json(build_model_info(spec, &model_state)))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:4904`. Registration: `akasha-daemon/src/main.rs:4747`.

<a id="delete-v1-models-model-id" />

## DELETE `/v1/models/:model_id` [#delete-v1modelsmodel_id]

DELETE /v1/models/:model\_id - Delete a model (unloads and removes from cache)

| Availability         | Source contract                                                  |
| -------------------- | ---------------------------------------------------------------- |
| Registration         | `always registered`                                              |
| 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-6]

**Path** — `String`

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

### Response [#response-6]

**Declared return:** `Result<Json<ModelOpResponse>, 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
ModelOpResponse {
        success: true,
        model_id: model_id.clone(),
        status: "not_downloaded".to_string(),
        message: format!("Model '{}' deleted from cache and unloaded", model_id),
    }
```

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

Directly referenced error variants: `Internal`, `InvalidRequest`. 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 models_delete(
        State(state): State<AppState>,
        Path(model_id): Path<String>,
    ) -> Result<Json<ModelOpResponse>, DaemonError> {
        state.record_http_request();
        let manager = require_model_manager(&state)?;

        // Verify the model exists in registry
        if manager.get_spec(&model_id).is_none() {
            return Err(DaemonError::InvalidRequest(format!(
                "model '{}' not found in registry",
                model_id
            )));
        }

        manager
            .delete_model(&model_id)
            .await
            .map_err(|e| DaemonError::Internal(format!("model delete failed: {}", e)))?;

        Ok(Json(ModelOpResponse {
            success: true,
            model_id: model_id.clone(),
            status: "not_downloaded".to_string(),
            message: format!("Model '{}' deleted from cache and unloaded", model_id),
        }))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:5048`. Registration: `akasha-daemon/src/main.rs:4747`.

<a id="get-v1-models-model-id-status" />

## GET `/v1/models/:model_id/status` [#get-v1modelsmodel_idstatus]

GET /v1/models/:model\_id/status - Get model status

| Availability         | Source contract                                                  |
| -------------------- | ---------------------------------------------------------------- |
| Registration         | `always registered`                                              |
| 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-7]

**Path** — `String`

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

### Response [#response-7]

**Declared return:** `Result<Json<Value>, 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
json!({
        "model_id": model_state.id,
        "name": model_state.name,
        "status": model_state.status.to_string(),
        "size_bytes": model_state.size_bytes,
        "memory_bytes": model_state.memory_bytes,
        "load_time_ms": model_state.load_time_ms,
        "last_error": model_state.last_error,
        "downloaded_at": model_state.downloaded_at.map(|dt| dt.to_rfc3339()),
        "loaded_at": model_state.loaded_at.map(|dt| dt.to_rfc3339()),
        "handle": handle_info,
    })
```

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

Directly referenced error variants: `InvalidRequest`. 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 models_status(
        State(state): State<AppState>,
        Path(model_id): Path<String>,
    ) -> Result<Json<Value>, DaemonError> {
        state.record_http_request();
        let manager = require_model_manager(&state)?;

        let model_state = manager
            .get_state(&model_id)
            .await
            .ok_or_else(|| DaemonError::InvalidRequest(format!("model '{}' not found", model_id)))?;

        // Gather handle info if loaded
        let handle_info = manager.get_handle(&model_id).await.map(|handle| {
            json!({
                "memory_bytes": handle.memory_bytes,
                "uptime_seconds": handle.uptime().as_secs(),
                "path": handle.path.display().to_string(),
            })
        });

        Ok(Json(json!({
            "model_id": model_state.id,
            "name": model_state.name,
            "status": model_state.status.to_string(),
            "size_bytes": model_state.size_bytes,
            "memory_bytes": model_state.memory_bytes,
            "load_time_ms": model_state.load_time_ms,
            "last_error": model_state.last_error,
            "downloaded_at": model_state.downloaded_at.map(|dt| dt.to_rfc3339()),
            "loaded_at": model_state.loaded_at.map(|dt| dt.to_rfc3339()),
            "handle": handle_info,
        })))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:4924`. Registration: `akasha-daemon/src/main.rs:4751`.