# Administration

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

Source: https://docs.minds.sh/docs/api/instance/administration



This reference covers **3 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                                             |
| ------ | ------------------------- | ----------------------------------------------------- |
| `POST` | `/admin/services/enable`  | [Admin enable service](#post-admin-services-enable)   |
| `POST` | `/admin/services/disable` | [Admin disable service](#post-admin-services-disable) |
| `GET`  | `/admin/services/status`  | [Admin service status](#get-admin-services-status)    |

<a id="post-admin-services-enable" />

## POST `/admin/services/enable` [#post-adminservicesenable]

Admin API: Enable service(s) at runtime (hot-loading)

| 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:** Admin middleware: source IP allowlist and x-akasha-admin-token; see authentication. Instance owner credentials alone do not grant daemon-global administration.

### Request [#request]

**Json** — `EnableServiceRequest`

```rust
enum EnableServiceRequest {
    /// Enable single service: {"service": "analytics"}
    Single { service: String },
    /// Enable multiple services: {"services": ["analytics", "graph"]}
    Multiple { services: Vec<String> },
}
```

### Response [#response]

**Declared return:** `Result<Json<EnableServiceResponse>, 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
EnableServiceResponse {
        success: failed.is_empty(),
        updates,
        failed_services: failed,
    }
```

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

Directly referenced error variants: `Internal`. 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 admin_enable_service(
        State(state): State<AppState>,
        ConnectInfo(client_addr): ConnectInfo<SocketAddr>,
        Json(req): Json<EnableServiceRequest>,
    ) -> Result<Json<EnableServiceResponse>, DaemonError> {
        state.record_http_request();

        let services: Vec<String> = match req {
            EnableServiceRequest::Single { service } => vec![service],
            EnableServiceRequest::Multiple { services } => services,
        }
        .into_iter()
        .map(|name| name.to_ascii_lowercase())
        .collect();

        tracing::info!(
            target: "akasha::admin",
            event = "service_enable_request",
            ?services,
            %client_addr,
            "Admin API: enable services request"
        );

        let mut updates = Vec::new();
        let mut failed = Vec::new();
        let mut dirty = false;

        {
            let mut runtime = state.service_runtime.write().await;
            for service_name in services {
                let service_label = service_name.clone();
                if runtime.entry(&service_name).is_none() {
                    failed.push(FailedService::new(
                        service_label.clone(),
                        "service not recognized",
                        "unknown_service",
                    ));
                    state
                        .metrics
                        .record_hotload("enable", &service_label, "unknown");
                    continue;
                }

                let unmet = runtime.dependency_failures(&service_name);
                if !unmet.is_empty() {
                    failed.push(FailedService::new(
                        service_name.clone(),
                        format!("unmet dependencies: {}", unmet.join(", ")),
                        "dependency_failed",
                    ));
                    state.metrics.record_dependency_failure(&service_label);
                    state
                        .metrics
                        .record_hotload("enable", &service_label, "dependency_failed");
                    continue;
                }

                match runtime.enable(&service_name) {
                    Ok(update) => {
                        dirty = true;
                        let response = ServiceMutationResponse::from(update);
                        let outcome = if response.applied {
                            "applied"
                        } else {
                            "restart_pending"
                        };
                        state
                            .metrics
                            .record_hotload("enable", &service_label, outcome);
                        updates.push(response);
                    }
                    Err(err) => {
                        failed.push(FailedService::new(
                            service_label.clone(),
                            err.to_string(),
                            "runtime_state_error",
                        ));
                        state
                            .metrics
                            .record_hotload("enable", &service_label, "runtime_state_error");
                    }
                }
            }
        }

        if dirty {
            state
                .persist_runtime_snapshot()
                .await
                .map_err(|e| DaemonError::Internal(format!("failed to persist runtime state: {e}")))?;
        }

        tracing::info!(
            target: "akasha::admin",
            event = "service_enable_completed",
            %client_addr,
            updates = updates.len(),
            failures = failed.len(),
            "Admin API: enable services completed"
        );

        Ok(Json(EnableServiceResponse {
            success: failed.is_empty(),
            updates,
            failed_services: failed,
        }))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:9983`. Registration: `akasha-daemon/src/main.rs:4333`.

<a id="post-admin-services-disable" />

## POST `/admin/services/disable` [#post-adminservicesdisable]

Admin API: Disable service(s) at runtime

| 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:** Admin middleware: source IP allowlist and x-akasha-admin-token; see authentication. Instance owner credentials alone do not grant daemon-global administration.

### Request [#request-1]

**Json** — `DisableServiceRequest`

```rust
enum DisableServiceRequest {
    Single { service: String },
    Multiple { services: Vec<String> },
}
```

### Response [#response-1]

**Declared return:** `Result<Json<DisableServiceResponse>, 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
DisableServiceResponse {
        success: failed.is_empty(),
        updates,
        failed_services: failed,
    }
```

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

Directly referenced error variants: `Internal`. 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 admin_disable_service(
        State(state): State<AppState>,
        ConnectInfo(client_addr): ConnectInfo<SocketAddr>,
        Json(req): Json<DisableServiceRequest>,
    ) -> Result<Json<DisableServiceResponse>, DaemonError> {
        state.record_http_request();

        let services: Vec<String> = match req {
            DisableServiceRequest::Single { service } => vec![service],
            DisableServiceRequest::Multiple { services } => services,
        }
        .into_iter()
        .map(|name| name.to_ascii_lowercase())
        .collect();

        tracing::info!(
            target: "akasha::admin",
            event = "service_disable_request",
            %client_addr,
            ?services,
            "Admin API: disable services request"
        );

        let mut updates = Vec::new();
        let mut failed = Vec::new();
        let mut dirty = false;

        {
            let mut runtime = state.service_runtime.write().await;
            for service_name in services {
                let service_label = service_name.clone();
                if runtime.entry(&service_name).is_none() {
                    failed.push(FailedService::new(
                        service_label.clone(),
                        "service not recognized",
                        "unknown_service",
                    ));
                    state
                        .metrics
                        .record_hotload("disable", &service_label, "unknown");
                    continue;
                }

                let dependents = runtime.active_dependents(&service_name);
                if !dependents.is_empty() {
                    failed.push(FailedService::new(
                        service_label.clone(),
                        format!(
                            "disable dependent services first: {}",
                            dependents.join(", ")
                        ),
                        "dependents_active",
                    ));
                    state.metrics.record_dependency_failure(&service_label);
                    state
                        .metrics
                        .record_hotload("disable", &service_label, "dependents_active");
                    continue;
                }

                match runtime.disable(&service_name) {
                    Ok(update) => {
                        dirty = true;
                        let response = ServiceMutationResponse::from(update);
                        let outcome = if response.applied {
                            "applied"
                        } else {
                            "restart_pending"
                        };
                        state
                            .metrics
                            .record_hotload("disable", &service_label, outcome);
                        updates.push(response);
                    }
                    Err(err) => {
                        failed.push(FailedService::new(
                            service_label.clone(),
                            err.to_string(),
                            "runtime_state_error",
                        ));
                        state
                            .metrics
                            .record_hotload("disable", &service_label, "runtime_state_error");
                    }
                }
            }
        }

        if dirty {
            state
                .persist_runtime_snapshot()
                .await
                .map_err(|e| DaemonError::Internal(format!("failed to persist runtime state: {e}")))?;
        }

        tracing::info!(
            target: "akasha::admin",
            event = "service_disable_completed",
            %client_addr,
            updates = updates.len(),
            failures = failed.len(),
            "Admin API: disable services completed"
        );

        Ok(Json(DisableServiceResponse {
            success: failed.is_empty(),
            updates,
            failed_services: failed,
        }))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:10128`. Registration: `akasha-daemon/src/main.rs:4334`.

<a id="get-admin-services-status" />

## GET `/admin/services/status` [#get-adminservicesstatus]

Admin API: Get current service 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:** Admin middleware: source IP allowlist and x-akasha-admin-token; see authentication. Instance owner credentials alone do not grant daemon-global administration.

### Request [#request-2]

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

**Declared return:** `Result<Json<ServiceStatusResponse>, 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
ServiceStatusResponse { services }
```

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

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 admin_service_status(
        State(state): State<AppState>,
        ConnectInfo(client_addr): ConnectInfo<SocketAddr>,
    ) -> Result<Json<ServiceStatusResponse>, DaemonError> {
        state.record_http_request();

        tracing::info!(
            target: "akasha::admin",
            event = "service_status_request",
            %client_addr,
            "Admin API: service status requested"
        );

        let mut services = {
            let runtime = state.service_runtime.read().await;
            runtime
                .entries()
                .map(|(_, entry)| entry.clone())
                .collect::<Vec<_>>()
        };
        for entry in &mut services {
            overlay_live_subsystem_state(&state, entry);
        }

        tracing::info!(
            target: "akasha::admin",
            event = "service_status_response",
            %client_addr,
            service_count = services.len(),
            "Admin API: service status response sent"
        );

        Ok(Json(ServiceStatusResponse { services }))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:10092`. Registration: `akasha-daemon/src/main.rs:4335`.