# Knowledge Graph

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

Source: https://docs.minds.sh/docs/api/instance/knowledge-graph



This reference covers **17 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/graph/cypher`                 | [Graph cypher](#post-v1-graph-cypher)                                 |
| `POST` | `/v1/graph/cypher-lite`            | [Graph cypher lite](#post-v1-graph-cypher-lite)                       |
| `POST` | `/v1/graph/index/ensure/property`  | [Graph index ensure property](#post-v1-graph-index-ensure-property)   |
| `POST` | `/v1/graph/index/ensure/composite` | [Graph index ensure composite](#post-v1-graph-index-ensure-composite) |
| `GET`  | `/v1/graph/index/stats`            | [Graph index stats](#get-v1-graph-index-stats)                        |
| `POST` | `/v1/graph/fulltext/search`        | [Graph fulltext search](#post-v1-graph-fulltext-search)               |
| `POST` | `/v1/graph/subdomain/query`        | [Graph subdomain query](#post-v1-graph-subdomain-query)               |
| `POST` | `/v1/graph/alg/pagerank`           | [Graph pagerank](#post-v1-graph-alg-pagerank)                         |
| `POST` | `/v1/graph/alg/shortest_path`      | [Graph shortest path](#post-v1-graph-alg-shortest-path)               |
| `POST` | `/v1/graph/alg/components`         | [Graph components](#post-v1-graph-alg-components)                     |
| `POST` | `/v1/graph/microtheory/switch`     | [Graph microtheory switch](#post-v1-graph-microtheory-switch)         |
| `POST` | `/v1/graph/microtheory/keyspace`   | [Graph microtheory keyspace](#post-v1-graph-microtheory-keyspace)     |
| `POST` | `/v1/graph/tx/begin`               | [Graph tx begin](#post-v1-graph-tx-begin)                             |
| `POST` | `/v1/graph/tx/commit`              | [Graph tx commit](#post-v1-graph-tx-commit)                           |
| `POST` | `/v1/graph/tx/rollback`            | [Graph tx rollback](#post-v1-graph-tx-rollback)                       |
| `GET`  | `/v1/graph/schema`                 | [Graph schema metadata](#get-v1-graph-schema)                         |
| `GET`  | `/v1/graph/health`                 | [Graph health](#get-v1-graph-health)                                  |

<a id="post-v1-graph-cypher" />

## POST `/v1/graph/cypher` [#post-v1graphcypher]

Graph cypher

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

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

### Request [#request]

**Json** — `CypherRequest`

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

```rust
struct CypherRequest {
    query: String,
}
```

### 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
serde_json::json!({"rows": rows})
```

### 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 graph_cypher(
        State(state): State<AppState>,
        Extension(db): Extension<Arc<AkashaDB>>,
        Json(req): Json<CypherRequest>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        state.usage_emitter.emit_graph_traversal();
        let rows = db
            .cypher(&req.query)
            .await
            .map_err(|e| DaemonError::InvalidRequest(e.to_string()))?;
        Ok(Json(serde_json::json!({"rows": rows})))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:2292`. Registration: `akasha-daemon/src/main.rs:4426`.

<a id="post-v1-graph-cypher-lite" />

## POST `/v1/graph/cypher-lite` [#post-v1graphcypher-lite]

Graph cypher lite

| Availability         | Source contract                            |
| -------------------- | ------------------------------------------ |
| Registration         | `config.enable_graph`                      |
| Runtime service      | `graph`                                    |
| 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** — `CypherLiteRequest`

| Field                  | Rust type                       | Required on input         | Notes |
| ---------------------- | ------------------------------- | ------------------------- | ----- |
| `query`                | `String`                        | Yes                       |       |
| `allow_updates`        | `Option<bool>`                  | No; optional or defaulted |       |
| `enforce_transactions` | `Option<bool>`                  | No; optional or defaulted |       |
| `temporal`             | `Option<TemporalClauseRequest>` | No; optional or defaulted |       |

```rust
struct CypherLiteRequest {
    query: String,
    allow_updates: Option<bool>,
    enforce_transactions: Option<bool>,
    temporal: Option<TemporalClauseRequest>,
}
```

### 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
serde_json::json!({"rows": rows})
```

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

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 graph_cypher_lite(
        State(state): State<AppState>,
        Extension(db): Extension<Arc<AkashaDB>>,
        Json(req): Json<CypherLiteRequest>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        state.usage_emitter.emit_graph_traversal();
        let mut options = CypherLiteOptions {
            allow_updates: req.allow_updates.unwrap_or(false),
            enforce_transactions: req.enforce_transactions.unwrap_or(true),
            ..Default::default()
        };

        if let Some(temporal) = req.temporal {
            let valid_time = maybe_ts_to_datetime(temporal.valid_time)?;
            let transaction_time = maybe_ts_to_datetime(temporal.transaction_time)?;
            let valid_range = match temporal.valid_range {
                Some(range) => Some((ts_to_datetime(range.from)?, ts_to_datetime(range.to)?)),
                None => None,
            };

            options.temporal = Some(TemporalClause {
                valid_time,
                transaction_time,
                valid_range,
            });
        }

        let span = tracing::info_span!(
            "graph_cypher_lite",
            allow_updates = options.allow_updates,
            has_temporal = options.temporal.is_some()
        );
        let _guard = span.enter();
        let start = std::time::Instant::now();
        let rows = db
            .cypher_lite(&req.query, options)
            .await
            .map_err(|e| DaemonError::InvalidRequest(e.to_string()))?;
        let elapsed = start.elapsed();
        tracing::info!(
            row_count = rows.len(),
            elapsed_ms = elapsed.as_millis() as u64,
            "Cypher-lite query executed"
        );
        Ok(Json(serde_json::json!({"rows": rows})))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:2306`. Registration: `akasha-daemon/src/main.rs:4427`.

<a id="post-v1-graph-index-ensure-property" />

## POST `/v1/graph/index/ensure/property` [#post-v1graphindexensureproperty]

Graph index ensure property

| Availability         | Source contract                            |
| -------------------- | ------------------------------------------ |
| Registration         | `config.enable_graph`                      |
| Runtime service      | `graph`                                    |
| 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** — `EnsurePropertyIndexRequest`

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

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

### 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 graph_index_ensure_property(
        State(state): State<AppState>,
        Extension(db): Extension<Arc<AkashaDB>>,
        Json(req): Json<EnsurePropertyIndexRequest>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        db.graph_ensure_property_index(&req.property_name)
            .await
            .map_err(|e| DaemonError::InvalidRequest(e.to_string()))?;
        Ok(Json(serde_json::json!({"ok": true})))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:2369`. Registration: `akasha-daemon/src/main.rs:4428`.

<a id="post-v1-graph-index-ensure-composite" />

## POST `/v1/graph/index/ensure/composite` [#post-v1graphindexensurecomposite]

Graph index ensure composite

| Availability         | Source contract                            |
| -------------------- | ------------------------------------------ |
| Registration         | `config.enable_graph`                      |
| Runtime service      | `graph`                                    |
| 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** — `EnsureCompositeIndexRequest`

| Field        | Rust type     | Required on input | Notes |
| ------------ | ------------- | ----------------- | ----- |
| `properties` | `Vec<String>` | Yes               |       |

```rust
struct EnsureCompositeIndexRequest {
    properties: Vec<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: `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 graph_index_ensure_composite(
        State(state): State<AppState>,
        Extension(db): Extension<Arc<AkashaDB>>,
        Json(req): Json<EnsureCompositeIndexRequest>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        let props: Vec<&str> = req.properties.iter().map(|s| s.as_str()).collect();
        db.graph_ensure_composite_index(&props)
            .await
            .map_err(|e| DaemonError::InvalidRequest(e.to_string()))?;
        Ok(Json(serde_json::json!({"ok": true})))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:2386`. Registration: `akasha-daemon/src/main.rs:4432`.

<a id="get-v1-graph-index-stats" />

## GET `/v1/graph/index/stats` [#get-v1graphindexstats]

Graph index stats

| Availability         | Source contract                            |
| -------------------- | ------------------------------------------ |
| Registration         | `config.enable_graph`                      |
| Runtime service      | `graph`                                    |
| 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
stats
```

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

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 graph_index_stats(
        State(state): State<AppState>,
        Extension(db): Extension<Arc<AkashaDB>>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        let stats = db
            .graph_index_stats()
            .await
            .map_err(|e| DaemonError::InvalidRequest(e.to_string()))?;
        Ok(Json(stats))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:2399`. Registration: `akasha-daemon/src/main.rs:4436`.

<a id="post-v1-graph-fulltext-search" />

## POST `/v1/graph/fulltext/search` [#post-v1graphfulltextsearch]

Graph fulltext search

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

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

### Request [#request-5]

**Json** — `GraphFulltextRequest`

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

```rust
struct GraphFulltextRequest {
    query: String,
    limit: Option<usize>,
}
```

### 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!({"rows": rows})
```

### 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 graph_fulltext_search(
        State(state): State<AppState>,
        Extension(db): Extension<Arc<AkashaDB>>,
        Json(req): Json<GraphFulltextRequest>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        let limit = req.limit.unwrap_or(10);
        let rows = db
            .graph_text_search(&req.query, limit)
            .await
            .map_err(|e| DaemonError::InvalidRequest(e.to_string()))?;
        Ok(Json(serde_json::json!({"rows": rows})))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:2417`. Registration: `akasha-daemon/src/main.rs:4437`.

<a id="post-v1-graph-subdomain-query" />

## POST `/v1/graph/subdomain/query` [#post-v1graphsubdomainquery]

Graph subdomain query

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

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

### Request [#request-6]

**Json** — `SubdomainQueryReq`

| Field       | Rust type       | Required on input         | Notes |
| ----------- | --------------- | ------------------------- | ----- |
| `namespace` | `String`        | Yes                       |       |
| `domain`    | `String`        | Yes                       |       |
| `subdomain` | `String`        | Yes                       |       |
| `limit`     | `Option<usize>` | No; optional or defaulted |       |

```rust
struct SubdomainQueryReq {
    namespace: String,
    domain: String,
    subdomain: String,
    limit: Option<usize>,
}
```

### 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!({"rows": rows})
```

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

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 graph_subdomain_query(
        State(state): State<AppState>,
        Extension(db): Extension<Arc<AkashaDB>>,
        Json(req): Json<SubdomainQueryReq>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        let rows: Vec<AkJsonValue> = db
            .query_subdomain(&req.namespace, &req.domain, &req.subdomain, req.limit)
            .await
            .map_err(|e| DaemonError::InvalidRequest(e.to_string()))?;
        Ok(Json(serde_json::json!({"rows": rows})))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:2459`. Registration: `akasha-daemon/src/main.rs:4438`.

<a id="post-v1-graph-alg-pagerank" />

## POST `/v1/graph/alg/pagerank` [#post-v1graphalgpagerank]

Graph pagerank

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

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

### Request [#request-7]

**Json** — `PagerankRequest`

| Field     | Rust type     | Required on input         | Notes |
| --------- | ------------- | ------------------------- | ----- |
| `damping` | `Option<f64>` | No; optional or defaulted |       |

```rust
struct PagerankRequest {
    damping: Option<f64>,
}
```

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

### 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 graph_pagerank(
        State(state): State<AppState>,
        Extension(db): Extension<Arc<AkashaDB>>,
        Json(req): Json<PagerankRequest>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        let r = db
            .graph_pagerank(req.damping)
            .await
            .map_err(|e| DaemonError::InvalidRequest(e.to_string()))?;
        // `graph_pagerank` already returns the full `{scores, max_score, ...}` shape.
        Ok(Json(r))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:2477`. Registration: `akasha-daemon/src/main.rs:4439`.

<a id="post-v1-graph-alg-shortest-path" />

## POST `/v1/graph/alg/shortest_path` [#post-v1graphalgshortest_path]

Graph shortest path

| Availability         | Source contract                            |
| -------------------- | ------------------------------------------ |
| Registration         | `config.enable_graph`                      |
| Runtime service      | `graph`                                    |
| 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** — `ShortestPathRequest`

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

```rust
struct ShortestPathRequest {
    source: String,
    target: String,
}
```

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

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

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 graph_shortest_path(
        State(state): State<AppState>,
        Extension(db): Extension<Arc<AkashaDB>>,
        Json(req): Json<ShortestPathRequest>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        let s = uuid::Uuid::parse_str(&req.source)
            .map_err(|_| DaemonError::InvalidRequest("invalid source".into()))?;
        let t = uuid::Uuid::parse_str(&req.target)
            .map_err(|_| DaemonError::InvalidRequest("invalid target".into()))?;
        let r = db
            .graph_shortest_path(s, t)
            .await
            .map_err(|e| DaemonError::InvalidRequest(e.to_string()))?;
        // `graph_shortest_path` returns a structured `{found, path, edges, ...}` object.
        Ok(Json(r))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:2497`. Registration: `akasha-daemon/src/main.rs:4440`.

<a id="post-v1-graph-alg-components" />

## POST `/v1/graph/alg/components` [#post-v1graphalgcomponents]

Graph components

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

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

### Request [#request-9]

**Json** — `ComponentsRequest`

| Field    | Rust type      | Required on input         | Notes |
| -------- | -------------- | ------------------------- | ----- |
| `strong` | `Option<bool>` | No; optional or defaulted |       |

```rust
struct ComponentsRequest {
    strong: Option<bool>,
}
```

### 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!({"communities": serde_json::to_value(&r).unwrap_or_default()}),
```

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

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 graph_components(
        State(state): State<AppState>,
        Extension(db): Extension<Arc<AkashaDB>>,
        Json(req): Json<ComponentsRequest>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        let r = db
            .graph_connected_components(req.strong.unwrap_or(false))
            .await
            .map_err(|e| DaemonError::InvalidRequest(e.to_string()))?;
        Ok(Json(
            serde_json::json!({"communities": serde_json::to_value(&r).unwrap_or_default()}),
        ))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:2520`. Registration: `akasha-daemon/src/main.rs:4441`.

<a id="post-v1-graph-microtheory-switch" />

## POST `/v1/graph/microtheory/switch` [#post-v1graphmicrotheoryswitch]

Graph microtheory switch

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

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

### Request [#request-10]

**Json** — `MicrotheorySwitchRequest`

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

```rust
struct MicrotheorySwitchRequest {
    name: String,
}
```

### Response [#response-10]

**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, "keyspace": keyspace})
```

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

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 graph_microtheory_switch(
        State(state): State<AppState>,
        Extension(db): Extension<Arc<AkashaDB>>,
        Json(req): Json<MicrotheorySwitchRequest>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        let keyspace = db
            .graph_switch_microtheory(&req.name)
            .await
            .map_err(|e| DaemonError::InvalidRequest(e.to_string()))?;
        Ok(Json(serde_json::json!({"ok": true, "keyspace": keyspace})))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:2540`. Registration: `akasha-daemon/src/main.rs:4442`.

<a id="post-v1-graph-microtheory-keyspace" />

## POST `/v1/graph/microtheory/keyspace` [#post-v1graphmicrotheorykeyspace]

Graph microtheory keyspace

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

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

### Request [#request-11]

**Json** — `MicrotheoryKeyspaceRequest`

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

```rust
struct MicrotheoryKeyspaceRequest {
    name: String,
}
```

### Response [#response-11]

**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, "keyspace": keyspace})
```

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

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 graph_microtheory_keyspace(
        State(state): State<AppState>,
        Extension(db): Extension<Arc<AkashaDB>>,
        Json(req): Json<MicrotheoryKeyspaceRequest>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        // Ensure the microtheory keyspace exists and report its concrete name.
        let keyspace = db
            .graph_switch_microtheory(&req.name)
            .await
            .map_err(|e| DaemonError::InvalidRequest(e.to_string()))?;
        Ok(Json(serde_json::json!({"ok": true, "keyspace": keyspace})))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:2558`. Registration: `akasha-daemon/src/main.rs:4446`.

<a id="post-v1-graph-tx-begin" />

## POST `/v1/graph/tx/begin` [#post-v1graphtxbegin]

Graph tx begin

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

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

### Request [#request-12]

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

**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!({"tx_id": id.to_string()})
```

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

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 graph_tx_begin(
        State(state): State<AppState>,
        Extension(db): Extension<Arc<AkashaDB>>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        let db = db.clone();
        let tx_id = db
            .graph_tx_begin()
            .await
            .map_err(|e| DaemonError::InvalidRequest(e.to_string()))?;
        let id = uuid::Uuid::new_v4();
        {
            let mut m = state.graph_tx_map.write().await;
            m.insert(id, tx_id);
        }
        Ok(Json(serde_json::json!({"tx_id": id.to_string()})))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:9565`. Registration: `akasha-daemon/src/main.rs:4450`.

<a id="post-v1-graph-tx-commit" />

## POST `/v1/graph/tx/commit` [#post-v1graphtxcommit]

Graph tx commit

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

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

### Request [#request-13]

**Json** — `GraphTxIdReq`

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

```rust
struct GraphTxIdReq {
    id: String,
}
```

### Response [#response-13]

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

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 graph_tx_commit(
        State(state): State<AppState>,
        Extension(db): Extension<Arc<AkashaDB>>,
        Json(req): Json<GraphTxIdReq>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        let id = uuid::Uuid::parse_str(&req.id)
            .map_err(|_| DaemonError::InvalidRequest("invalid id".into()))?;
        let tx_id = {
            let mut m = state.graph_tx_map.write().await;
            m.remove(&id)
                .ok_or_else(|| DaemonError::InvalidRequest("unknown graph tx".into()))?
        };
        db.graph_tx_commit(tx_id)
            .await
            .map_err(|e| DaemonError::InvalidRequest(e.to_string()))?;
        Ok(Json(serde_json::json!({"ok": true})))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:9583`. Registration: `akasha-daemon/src/main.rs:4451`.

<a id="post-v1-graph-tx-rollback" />

## POST `/v1/graph/tx/rollback` [#post-v1graphtxrollback]

Graph tx rollback

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

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

### Request [#request-14]

**Json** — `GraphTxIdReq`

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

```rust
struct GraphTxIdReq {
    id: String,
}
```

### Response [#response-14]

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

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 graph_tx_rollback(
        State(state): State<AppState>,
        Extension(db): Extension<Arc<AkashaDB>>,
        Json(req): Json<GraphTxIdReq>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        let id = uuid::Uuid::parse_str(&req.id)
            .map_err(|_| DaemonError::InvalidRequest("invalid id".into()))?;
        let tx_id = {
            let mut m = state.graph_tx_map.write().await;
            m.remove(&id)
                .ok_or_else(|| DaemonError::InvalidRequest("unknown graph tx".into()))?
        };
        db.graph_tx_rollback(tx_id)
            .await
            .map_err(|e| DaemonError::InvalidRequest(e.to_string()))?;
        Ok(Json(serde_json::json!({"ok": true})))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:9602`. Registration: `akasha-daemon/src/main.rs:4452`.

<a id="get-v1-graph-schema" />

## GET `/v1/graph/schema` [#get-v1graphschema]

Graph schema metadata

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

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

### Request [#request-15]

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

**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
metadata
```

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

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 graph_schema_metadata(
        State(state): State<AppState>,
        Extension(db): Extension<Arc<AkashaDB>>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        let start = std::time::Instant::now();
        let metadata = db
            .graph_schema_metadata()
            .await
            .map_err(|e| DaemonError::InvalidRequest(e.to_string()))?;
        tracing::info!(
            elapsed_ms = start.elapsed().as_millis() as u64,
            node_types = metadata.node_schemas.len(),
            edge_types = metadata.edge_schemas.len(),
            "Graph schema metadata fetched"
        );
        Ok(Json(metadata))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:2431`. Registration: `akasha-daemon/src/main.rs:4453`.

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

## GET `/v1/graph/health` [#get-v1graphhealth]

Graph health

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

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

### Request [#request-16]

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

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

Serialization is delegated or the handler returns a raw response. Consult the exact handler below; the OpenAPI response intentionally remains unconstrained.

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

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 graph_health(State(state): State<AppState>) -> Result<impl IntoResponse, DaemonError> {
        service_health_payload(&state, "graph").await
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:10285`. Registration: `akasha-daemon/src/main.rs:4454`.