Model Management
Every registered model management instance operation, with source-derived inputs, outputs, access policy, and errors.
This reference covers 8 HTTP operations registered by the Akasha daemon. Call these paths on your instance base URL. See authentication, errors, and coverage before integrating.
| Method | Path | Operation |
|---|---|---|
GET | /v1/models | Models list |
POST | /v1/models/load | Models load |
POST | /v1/models/download | Models download |
GET | /v1/models/memory | Models memory usage |
GET | /v1/models/health | Models health |
GET | /v1/models/:model_id | Models get one |
DELETE | /v1/models/:model_id | Models delete |
GET | /v1/models/:model_id/status | Models status |
GET /v1/models
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
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
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.
ModelsListResponse {
models: model_infos,
total,
memory_used_bytes: memory_used,
memory_budget_bytes: memory_budget,
}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.
Source: akasha-daemon/src/main.rs:4877. Registration: akasha-daemon/src/main.rs:4742.
POST /v1/models/load
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
Json — ModelLoadRequest
| Field | Rust type | Required on input | Notes |
|---|---|---|---|
model_id | String | Yes | |
force_download | bool | No; optional or defaulted | Serde: default |
struct ModelLoadRequest {
model_id: String,
#[serde(default)]
force_download: bool,
}Response
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.
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
Directly referenced error variants: Internal, InvalidRequest. Middleware and delegated services can return additional errors described in the shared error reference.
Source: akasha-daemon/src/main.rs:4960. Registration: akasha-daemon/src/main.rs:4743.
POST /v1/models/download
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
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" |
struct ModelDownloadRequest {
model_id: String,
#[serde(default)]
force: bool,
#[serde(default = "default_verify_hash")]
verify_hash: bool,
}Response
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.
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
Directly referenced error variants: Internal, InvalidRequest. Middleware and delegated services can return additional errors described in the shared error reference.
Source: akasha-daemon/src/main.rs:5018. Registration: akasha-daemon/src/main.rs:4744.
GET /v1/models/memory
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
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
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.
ModelsMemoryResponse {
memory_used_bytes: memory_used,
memory_budget_bytes: memory_budget,
utilization_percent: utilization,
loaded_models,
}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.
Source: akasha-daemon/src/main.rs:5077. Registration: akasha-daemon/src/main.rs:4745.
GET /v1/models/health
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
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
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.
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
Directly referenced error variants: none in the handler body. Middleware and delegated services can return additional errors described in the shared error reference.
Source: akasha-daemon/src/main.rs:5114. Registration: akasha-daemon/src/main.rs:4746.
GET /v1/models/:model_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
Path — String
{
"type": "string"
}Response
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.
build_model_info(spec, &model_state)Errors and validation
Directly referenced error variants: InvalidRequest. Middleware and delegated services can return additional errors described in the shared error reference.
Source: akasha-daemon/src/main.rs:4904. Registration: akasha-daemon/src/main.rs:4747.
DELETE /v1/models/:model_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
Path — String
{
"type": "string"
}Response
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.
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
Directly referenced error variants: Internal, InvalidRequest. Middleware and delegated services can return additional errors described in the shared error reference.
Source: akasha-daemon/src/main.rs:5048. Registration: akasha-daemon/src/main.rs:4747.
GET /v1/models/:model_id/status
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
Path — String
{
"type": "string"
}Response
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.
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
Directly referenced error variants: InvalidRequest. Middleware and delegated services can return additional errors described in the shared error reference.
Source: akasha-daemon/src/main.rs:4924. Registration: akasha-daemon/src/main.rs:4751.