# Reasoning

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

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



This reference covers **10 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` | `/v1/ns/retrieve`           | [Ns retrieve](#post-v1-ns-retrieve)                     |
| `POST` | `/v1/ns/retrieve_with_mode` | [Ns retrieve with mode](#post-v1-ns-retrieve-with-mode) |
| `POST` | `/v1/ns/paths/find`         | [Ns paths find](#post-v1-ns-paths-find)                 |
| `POST` | `/v1/ns/prefetch/start`     | [Ns prefetch start](#post-v1-ns-prefetch-start)         |
| `POST` | `/v1/ns/prefetch/stop`      | [Ns prefetch stop](#post-v1-ns-prefetch-stop)           |
| `GET`  | `/v1/ns/cache/stats`        | [Ns cache stats](#get-v1-ns-cache-stats)                |
| `GET`  | `/v1/ns/history`            | [Ns history](#get-v1-ns-history)                        |
| `GET`  | `/v1/ns/rules`              | [Ns rules](#get-v1-ns-rules)                            |
| `POST` | `/v1/ns/rules/toggle`       | [Ns rules toggle](#post-v1-ns-rules-toggle)             |
| `GET`  | `/v1/ns/stats`              | [Ns stats](#get-v1-ns-stats)                            |

<a id="post-v1-ns-retrieve" />

## POST `/v1/ns/retrieve` [#post-v1nsretrieve]

Ns retrieve

| Availability         | Source contract                            |
| -------------------- | ------------------------------------------ |
| Registration         | `config.enable_neurosymbolic`              |
| Runtime service      | `neurosymbolic`                            |
| Handler dependencies | See handler source and return expressions. |

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

### Request [#request]

**Json** — `NsRetrieveReq`

| Field  | Rust type        | Required on input         | Notes |
| ------ | ---------------- | ------------------------- | ----- |
| `text` | `String`         | Yes                       |       |
| `mode` | `Option<String>` | No; optional or defaulted |       |
| `k`    | `Option<usize>`  | No; optional or defaulted |       |

```rust
struct NsRetrieveReq {
    text: String,
    mode: Option<String>,
    k: Option<usize>,
}
```

### 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
result
```

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

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 ns_retrieve(
        State(state): State<AppState>,
        Extension(db): Extension<Arc<AkashaDB>>,
        Json(req): Json<NsRetrieveReq>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        let _ = &req.mode;
        let rows = db
            .memory_retrieve(&req.text, req.k)
            .await
            .map_err(|e| DaemonError::InvalidRequest(e.to_string()))?;
        let result = serde_json::to_value(&rows).unwrap_or(serde_json::json!([]));
        // Record in ns_query_history
        {
            let entry = serde_json::json!({
                "query": &req.text,
                "k": req.k,
                "resultCount": rows.len(),
                "timestamp": chrono::Utc::now().to_rfc3339()
            });
            let mut history = state.ns_query_history.write().await;
            if history.len() >= 100 {
                history.pop_front();
            }
            history.push_back(entry);
        }
        Ok(Json(result))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:9479`. Registration: `akasha-daemon/src/main.rs:4502`.

<a id="post-v1-ns-retrieve-with-mode" />

## POST `/v1/ns/retrieve_with_mode` [#post-v1nsretrieve_with_mode]

Ns retrieve with mode

| Availability         | Source contract                            |
| -------------------- | ------------------------------------------ |
| Registration         | `config.enable_neurosymbolic`              |
| Runtime service      | `neurosymbolic`                            |
| 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** — `NsRetrieveReq`

| Field  | Rust type        | Required on input         | Notes |
| ------ | ---------------- | ------------------------- | ----- |
| `text` | `String`         | Yes                       |       |
| `mode` | `Option<String>` | No; optional or defaulted |       |
| `k`    | `Option<usize>`  | No; optional or defaulted |       |

```rust
struct NsRetrieveReq {
    text: String,
    mode: Option<String>,
    k: Option<usize>,
}
```

### 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
req
```

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

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 ns_retrieve_with_mode(
        State(state): State<AppState>,
        Extension(db): Extension<Arc<AkashaDB>>,
        Json(req): Json<NsRetrieveReq>,
    ) -> Result<impl IntoResponse, DaemonError> {
        ns_retrieve(State(state), Extension(db), Json(req)).await
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:9508`. Registration: `akasha-daemon/src/main.rs:4503`.

<a id="post-v1-ns-paths-find" />

## POST `/v1/ns/paths/find` [#post-v1nspathsfind]

Ns paths find

| Availability         | Source contract                            |
| -------------------- | ------------------------------------------ |
| Registration         | `config.enable_neurosymbolic`              |
| Runtime service      | `neurosymbolic`                            |
| 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** — `NsPathsFindReq`

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

```rust
struct NsPathsFindReq {
    start: String,
    end: 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
r
```

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

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 ns_paths_find(
        State(state): State<AppState>,
        Extension(db): Extension<Arc<AkashaDB>>,
        Json(req): Json<NsPathsFindReq>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        let s = uuid::Uuid::parse_str(&req.start)
            .map_err(|_| DaemonError::InvalidRequest("invalid start".into()))?;
        let t = uuid::Uuid::parse_str(&req.end)
            .map_err(|_| DaemonError::InvalidRequest("invalid end".into()))?;
        let r = db
            .graph_shortest_path(s, t)
            .await
            .map_err(|e| DaemonError::InvalidRequest(e.to_string()))?;
        Ok(Json(r))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:9522`. Registration: `akasha-daemon/src/main.rs:4504`.

<a id="post-v1-ns-prefetch-start" />

## POST `/v1/ns/prefetch/start` [#post-v1nsprefetchstart]

Ns prefetch start

| Availability         | Source contract                            |
| -------------------- | ------------------------------------------ |
| Registration         | `config.enable_neurosymbolic`              |
| Runtime service      | `neurosymbolic`                            |
| 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** — `NsPrefetchReq`

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

```rust
struct NsPrefetchReq {
    #[allow(dead_code)]
    query: 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
serde_json::json!({"ok": true})
```

### 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 ns_prefetch_start(
        Json(_req): Json<NsPrefetchReq>,
    ) -> Result<impl IntoResponse, DaemonError> {
        Ok(Json(serde_json::json!({"ok": true})))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:9545`. Registration: `akasha-daemon/src/main.rs:4505`.

<a id="post-v1-ns-prefetch-stop" />

## POST `/v1/ns/prefetch/stop` [#post-v1nsprefetchstop]

Ns prefetch stop

| Availability         | Source contract                            |
| -------------------- | ------------------------------------------ |
| Registration         | `config.enable_neurosymbolic`              |
| Runtime service      | `neurosymbolic`                            |
| 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<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
serde_json::json!({"ok": true})
```

### 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 ns_prefetch_stop() -> Result<impl IntoResponse, DaemonError> {
        Ok(Json(serde_json::json!({"ok": true})))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:9551`. Registration: `akasha-daemon/src/main.rs:4506`.

<a id="get-v1-ns-cache-stats" />

## GET `/v1/ns/cache/stats` [#get-v1nscachestats]

Ns cache stats

| Availability         | Source contract                            |
| -------------------- | ------------------------------------------ |
| Registration         | `config.enable_neurosymbolic`              |
| Runtime service      | `neurosymbolic`                            |
| Handler dependencies | See handler source and return expressions. |

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

### Request [#request-5]

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

**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
serde_json::json!({"hit_rate": 0.0})
```

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

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 ns_cache_stats() -> Result<impl IntoResponse, DaemonError> {
        Ok(Json(serde_json::json!({"hit_rate": 0.0})))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:9555`. Registration: `akasha-daemon/src/main.rs:4507`.

<a id="get-v1-ns-history" />

## GET `/v1/ns/history` [#get-v1nshistory]

Ns history

| Availability         | Source contract                            |
| -------------------- | ------------------------------------------ |
| Registration         | `config.enable_neurosymbolic`              |
| Runtime service      | `neurosymbolic`                            |
| Handler dependencies | See handler source and return expressions. |

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

### Request [#request-6]

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

**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
serde_json::json!(entries)
```

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

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 ns_history(State(state): State<AppState>) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        let history = state.ns_query_history.read().await;
        let entries: Vec<serde_json::Value> = history.iter().cloned().collect();
        Ok(Json(serde_json::json!(entries)))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:11191`. Registration: `akasha-daemon/src/main.rs:4508`.

<a id="get-v1-ns-rules" />

## GET `/v1/ns/rules` [#get-v1nsrules]

Ns rules

| Availability         | Source contract                            |
| -------------------- | ------------------------------------------ |
| Registration         | `config.enable_neurosymbolic`              |
| Runtime service      | `neurosymbolic`                            |
| Handler dependencies | See handler source and return expressions. |

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

### Request [#request-7]

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

**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
serde_json::json!([])
```

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

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 ns_rules(State(state): State<AppState>) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        Ok(Json(serde_json::json!([])))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:11198`. Registration: `akasha-daemon/src/main.rs:4509`.

<a id="post-v1-ns-rules-toggle" />

## POST `/v1/ns/rules/toggle` [#post-v1nsrulestoggle]

Ns rules toggle

| Availability         | Source contract                            |
| -------------------- | ------------------------------------------ |
| Registration         | `config.enable_neurosymbolic`              |
| Runtime service      | `neurosymbolic`                            |
| Handler dependencies | See handler source and return expressions. |

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

### Request [#request-8]

**Json** — `NsRuleToggleReq`

| Field     | Rust type | Required on input | Notes |
| --------- | --------- | ----------------- | ----- |
| `rule_id` | `String`  | Yes               |       |
| `enabled` | `bool`    | Yes               |       |

```rust
struct NsRuleToggleReq {
    #[allow(dead_code)]
    rule_id: String,
    #[allow(dead_code)]
    enabled: bool,
}
```

### Response [#response-8]

**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
serde_json::json!({"ok": true})
```

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

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 ns_rules_toggle(
        State(state): State<AppState>,
        Json(_req): Json<NsRuleToggleReq>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        Ok(Json(serde_json::json!({"ok": true})))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:11211`. Registration: `akasha-daemon/src/main.rs:4510`.

<a id="get-v1-ns-stats" />

## GET `/v1/ns/stats` [#get-v1nsstats]

Ns stats

| Availability         | Source contract                            |
| -------------------- | ------------------------------------------ |
| Registration         | `config.enable_neurosymbolic`              |
| Runtime service      | `neurosymbolic`                            |
| Handler dependencies | See handler source and return expressions. |

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

### Request [#request-9]

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

**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
serde_json::json!({
        "totalQueries": history.len(),
        "avgLatencyMs": 0,
        "cacheHitRate": 0.0,
        "activeRules": 0
    })
```

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

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 ns_stats(State(state): State<AppState>) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        let history = state.ns_query_history.read().await;
        Ok(Json(serde_json::json!({
            "totalQueries": history.len(),
            "avgLatencyMs": 0,
            "cacheHitRate": 0.0,
            "activeRules": 0
        })))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:11219`. Registration: `akasha-daemon/src/main.rs:4511`.