# Key Value

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

Source: https://docs.minds.sh/docs/api/instance/key-value



This reference covers **12 HTTP operations** registered by the Akasha daemon. Call these paths on your instance base URL. See [authentication](/docs/api/instance/authentication), [errors](/docs/api/instance/errors), and [coverage](/docs/api/instance/coverage) before integrating.

| Method   | Path                    | Operation                                              |
| -------- | ----------------------- | ------------------------------------------------------ |
| `GET`    | `/v1/kv/consistency`    | [Kv consistency](#get-v1-kv-consistency)               |
| `GET`    | `/v1/keyspaces`         | [List keyspaces](#get-v1-keyspaces)                    |
| `POST`   | `/v1/keyspaces`         | [Create keyspace](#post-v1-keyspaces)                  |
| `GET`    | `/v1/keyspaces/:name`   | [Get keyspace](#get-v1-keyspaces-name)                 |
| `DELETE` | `/v1/keyspaces/:name`   | [Delete keyspace](#delete-v1-keyspaces-name)           |
| `POST`   | `/v1/primitives/import` | [Import domain primitives](#post-v1-primitives-import) |
| `POST`   | `/v1/primitives/export` | [Export domain primitives](#post-v1-primitives-export) |
| `POST`   | `/v1/:keyspace`         | [Put item](#post-v1-keyspace)                          |
| `GET`    | `/v1/:keyspace/:id`     | [Get item](#get-v1-keyspace-id)                        |
| `DELETE` | `/v1/:keyspace/:id`     | [Delete item](#delete-v1-keyspace-id)                  |
| `POST`   | `/v1/:keyspace/query`   | [Query items](#post-v1-keyspace-query)                 |
| `GET`    | `/v1/stats`             | [Stats](#get-v1-stats)                                 |

<a id="get-v1-kv-consistency" />

## GET `/v1/kv/consistency` [#get-v1kvconsistency]

Kv consistency

| Availability         | Source contract                                                  |
| -------------------- | ---------------------------------------------------------------- |
| Registration         | `always registered`                                              |
| Runtime service      | No prefix-level service check; handler dependencies still apply. |
| Handler dependencies | See handler source and return expressions.                       |

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

### Request [#request]

No typed JSON, query, or path extractor is declared in the handler signature. Headers or request objects may still be consumed; the signature below is authoritative.

### Response [#response]

**Declared return:** `Result<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
report
```

### 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 kv_consistency(
        State(state): State<AppState>,
        Extension(db): Extension<Arc<AkashaDB>>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        let start = std::time::Instant::now();
        let report = db
            .akashakv()
            .run_consistency_check()
            .map_err(|e| DaemonError::InvalidRequest(e.to_string()))?;
        state
            .metrics
            .observe_health_latency("kv_consistency", start.elapsed());
        Ok(Json(report))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:3289`. Registration: `akasha-daemon/src/main.rs:4349`.

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

## GET `/v1/keyspaces` [#get-v1keyspaces]

List keyspaces

| Availability         | Source contract                                                  |
| -------------------- | ---------------------------------------------------------------- |
| Registration         | `config.enable_kv`                                               |
| 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. Handler additionally checks require(CoreAction::Read, None).

### Request [#request-1]

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.
&#x2A;*JSON field accesses in handler:** `name`. Nested lookups are included; this list alone does not establish requiredness.

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

### 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 list_keyspaces(
        State(state): State<AppState>,
        Extension(authority): Extension<RequestAuthority>,
        Extension(db): Extension<Arc<AkashaDB>>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        authority.require(CoreAction::Read, None)?;

        let keyspaces = db
            .list_keyspaces()
            .map_err(|e| DaemonError::Internal(e.to_string()))?
            .into_iter()
            .filter(|keyspace| {
                keyspace
                    .get("name")
                    .and_then(serde_json::Value::as_str)
                    .is_some_and(|name| authority.allows_keyspace(name))
            })
            .collect::<Vec<_>>();
        state.metrics.active_keyspaces.set(keyspaces.len() as i64);
        Ok(Json(keyspaces))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:3947`. Registration: `akasha-daemon/src/main.rs:4608`.

<a id="post-v1-keyspaces" />

## POST `/v1/keyspaces` [#post-v1keyspaces]

Create keyspace

| Availability         | Source contract                                                  |
| -------------------- | ---------------------------------------------------------------- |
| Registration         | `config.enable_kv`                                               |
| 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. Handler additionally checks require(CoreAction::Admin, Some(\&req.name)).

### Request [#request-2]

**Json** — `CreateKeyspaceRequest`

| Field            | Rust type                                    | Required on input         | Notes            |
| ---------------- | -------------------------------------------- | ------------------------- | ---------------- |
| `name`           | `String`                                     | Yes                       |                  |
| `model`          | `String`                                     | Yes                       |                  |
| `dims`           | `Option<usize>`                              | No; optional or defaulted |                  |
| `domain`         | `Option<String>`                             | No; optional or defaulted | Serde: `default` |
| `schema_version` | `Option<u32>`                                | No; optional or defaulted | Serde: `default` |
| `schema`         | `Option<serde_json::Value>`                  | No; optional or defaulted | Serde: `default` |
| `strict`         | `Option<bool>`                               | No; optional or defaulted | Serde: `default` |
| `metadata`       | `Option<HashMap<String, serde_json::Value>>` | No; optional or defaulted | Serde: `default` |
| `description`    | `Option<String>`                             | No; optional or defaulted | Serde: `default` |

```rust
struct CreateKeyspaceRequest {
    name: String,
    model: String,
    dims: Option<usize>,
    #[serde(default)]
    domain: Option<String>,
    #[serde(default)]
    schema_version: Option<u32>,
    #[serde(default)]
    schema: Option<serde_json::Value>,
    #[serde(default)]
    strict: Option<bool>,
    #[serde(default)]
    metadata: Option<HashMap<String, serde_json::Value>>,
    #[serde(default)]
    description: Option<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.

Explicit status constants: `CREATED`.

<Accordions>
  <Accordion title="Inspect implementation">
    This exact source excerpt includes validation, defaults, delegated calls, and response assembly.

    ```rust
    async fn create_keyspace(
        State(state): State<AppState>,
        Extension(authority): Extension<RequestAuthority>,
        Extension(db): Extension<Arc<AkashaDB>>,
        Json(req): Json<CreateKeyspaceRequest>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        authority.require(CoreAction::Admin, Some(&req.name))?;
        let model = map_model(&req)?;
        db.create_keyspace(&req.name, model)
            .await
            .map_err(|e| DaemonError::InvalidRequest(e.to_string()))?;
        Ok((StatusCode::CREATED, Json(serde_json::json!({"ok":true}))))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:3984`. Registration: `akasha-daemon/src/main.rs:4608`.

<a id="get-v1-keyspaces-name" />

## GET `/v1/keyspaces/:name` [#get-v1keyspacesname]

Get keyspace

| Availability         | Source contract                                                  |
| -------------------- | ---------------------------------------------------------------- |
| Registration         | `config.enable_kv`                                               |
| 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. Handler additionally checks require(CoreAction::Read, Some(\&name)).

### Request [#request-3]

**Path** — `String`

```json
{
  "type": "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
ks
```

### 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 get_keyspace(
        Path(name): Path<String>,
        State(state): State<AppState>,
        Extension(authority): Extension<RequestAuthority>,
        Extension(db): Extension<Arc<AkashaDB>>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        authority.require(CoreAction::Read, Some(&name))?;
        let ks = db
            .get_keyspace(&name)
            .map_err(|e| DaemonError::InvalidRequest(e.to_string()))?;
        Ok(Json(ks))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:3970`. Registration: `akasha-daemon/src/main.rs:4609`.

<a id="delete-v1-keyspaces-name" />

## DELETE `/v1/keyspaces/:name` [#delete-v1keyspacesname]

Delete keyspace

| Availability         | Source contract                                                  |
| -------------------- | ---------------------------------------------------------------- |
| Registration         | `config.enable_kv`                                               |
| 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. Handler additionally checks require(CoreAction::Admin, Some(\&id)).

### Request [#request-4]

**Path** — `String`

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

### 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: `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 delete_keyspace(
        Path(id): Path<String>,
        State(state): State<AppState>,
        Extension(authority): Extension<RequestAuthority>,
        Extension(db): Extension<Arc<AkashaDB>>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        authority.require(CoreAction::Admin, Some(&id))?;
        db.delete_keyspace(&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:4031`. Registration: `akasha-daemon/src/main.rs:4609`.

<a id="post-v1-primitives-import" />

## POST `/v1/primitives/import` [#post-v1primitivesimport]

Import domain primitives

| Availability         | Source contract                                                  |
| -------------------- | ---------------------------------------------------------------- |
| Registration         | `config.enable_kv`                                               |
| 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. Handler additionally checks require(CoreAction::Write, Some(\&req.keyspace)).

### Request [#request-5]

**Json** — `PrimitiveImportRequest`

| Field            | Rust type                | Required on input         | Notes            |
| ---------------- | ------------------------ | ------------------------- | ---------------- |
| `keyspace`       | `String`                 | Yes                       |                  |
| `records`        | `Vec<serde_json::Value>` | Yes                       |                  |
| `schema_version` | `Option<u32>`            | No; optional or defaulted |                  |
| `upsert`         | `bool`                   | No; optional or defaulted | Serde: `default` |

```rust
struct PrimitiveImportRequest {
    keyspace: String,
    records: Vec<serde_json::Value>,
    schema_version: Option<u32>,
    #[serde(default)]
    upsert: bool,
}
```

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

### 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 import_domain_primitives(
        State(state): State<AppState>,
        Extension(authority): Extension<RequestAuthority>,
        Extension(db): Extension<Arc<AkashaDB>>,
        Json(req): Json<PrimitiveImportRequest>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        authority.require(CoreAction::Write, Some(&req.keyspace))?;
        let summary = db
            .import_domain_primitives(&req.keyspace, &req.records, req.schema_version, req.upsert)
            .await
            .map_err(|e| DaemonError::InvalidRequest(e.to_string()))?;

        Ok(Json(summary))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:3999`. Registration: `akasha-daemon/src/main.rs:4613`.

<a id="post-v1-primitives-export" />

## POST `/v1/primitives/export` [#post-v1primitivesexport]

Export domain primitives

| Availability         | Source contract                                                  |
| -------------------- | ---------------------------------------------------------------- |
| Registration         | `config.enable_kv`                                               |
| 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. Handler additionally checks require(CoreAction::Query, Some(\&req.keyspace)).

### Request [#request-6]

**Json** — `PrimitiveExportRequest`

| Field            | Rust type     | Required on input         | Notes |
| ---------------- | ------------- | ------------------------- | ----- |
| `keyspace`       | `String`      | Yes                       |       |
| `schema_version` | `Option<u32>` | No; optional or defaulted |       |

```rust
struct PrimitiveExportRequest {
    keyspace: String,
    schema_version: Option<u32>,
}
```

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

### 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 export_domain_primitives(
        State(state): State<AppState>,
        Extension(authority): Extension<RequestAuthority>,
        Extension(db): Extension<Arc<AkashaDB>>,
        Json(req): Json<PrimitiveExportRequest>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        authority.require(CoreAction::Query, Some(&req.keyspace))?;
        let bundle = db
            .export_domain_primitives(&req.keyspace, req.schema_version)
            .await
            .map_err(|e| DaemonError::InvalidRequest(e.to_string()))?;

        Ok(Json(bundle))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:4015`. Registration: `akasha-daemon/src/main.rs:4614`.

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

## POST `/v1/:keyspace` [#post-v1keyspace]

Put item

| Availability         | Source contract                                                  |
| -------------------- | ---------------------------------------------------------------- |
| Registration         | `config.enable_kv`                                               |
| 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. Handler additionally checks require(CoreAction::Write, Some(\&keyspace)).

### Request [#request-7]

**Path** — `String`

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

**Json** — `PutRequest`

| Field  | Rust type           | Required on input | Notes |
| ------ | ------------------- | ----------------- | ----- |
| `data` | `serde_json::Value` | Yes               |       |

```rust
struct PutRequest {
    data: serde_json::Value,
}
```

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

### 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.

Explicit status constants: `CREATED`.

<Accordions>
  <Accordion title="Inspect implementation">
    This exact source excerpt includes validation, defaults, delegated calls, and response assembly.

    ```rust
    async fn put_item(
        Path(keyspace): Path<String>,
        State(state): State<AppState>,
        Extension(authority): Extension<RequestAuthority>,
        Extension(db): Extension<Arc<AkashaDB>>,
        Json(req): Json<PutRequest>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        authority.require(CoreAction::Write, Some(&keyspace))?;
        let id = db
            .put(&keyspace, &req.data)
            .await
            .map_err(|e| DaemonError::InvalidRequest(e.to_string()))?;
        Ok((StatusCode::CREATED, Json(serde_json::json!({"id": id}))))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:4045`. Registration: `akasha-daemon/src/main.rs:4615`.

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

## GET `/v1/:keyspace/:id` [#get-v1keyspaceid]

Get item

| Availability         | Source contract                                                  |
| -------------------- | ---------------------------------------------------------------- |
| Registration         | `config.enable_kv`                                               |
| 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. Handler additionally checks require(CoreAction::Read, Some(\&keyspace)).

### Request [#request-8]

**Path** — `(String, String)`

```json
{
  "x-rust-type": "(String, String)",
  "description": "Wire schema unresolved by the source extractor; no fields are invented."
}
```

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

### 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 get_item(
        Path((keyspace, id)): Path<(String, String)>,
        State(state): State<AppState>,
        Extension(authority): Extension<RequestAuthority>,
        Extension(db): Extension<Arc<AkashaDB>>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        authority.require(CoreAction::Read, Some(&keyspace))?;
        let item = db
            .get(&keyspace, &id)
            .await
            .map_err(|e| DaemonError::InvalidRequest(e.to_string()))?;
        Ok(Json(serde_json::json!({"data": item})))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:4061`. Registration: `akasha-daemon/src/main.rs:4616`.

<a id="delete-v1-keyspace-id" />

## DELETE `/v1/:keyspace/:id` [#delete-v1keyspaceid]

Delete item

| Availability         | Source contract                                                  |
| -------------------- | ---------------------------------------------------------------- |
| Registration         | `config.enable_kv`                                               |
| 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. Handler additionally checks require(CoreAction::Delete, Some(\&keyspace)).

### Request [#request-9]

**Path** — `(String, String)`

```json
{
  "x-rust-type": "(String, String)",
  "description": "Wire schema unresolved by the source extractor; no fields are invented."
}
```

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

### 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 delete_item(
        Path((keyspace, id)): Path<(String, String)>,
        State(state): State<AppState>,
        Extension(authority): Extension<RequestAuthority>,
        Extension(db): Extension<Arc<AkashaDB>>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        authority.require(CoreAction::Delete, Some(&keyspace))?;
        let deleted = db
            .delete(&keyspace, &id)
            .await
            .map_err(|e| DaemonError::InvalidRequest(e.to_string()))?;
        Ok(Json(serde_json::json!({"deleted": deleted})))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:4076`. Registration: `akasha-daemon/src/main.rs:4616`.

<a id="post-v1-keyspace-query" />

## POST `/v1/:keyspace/query` [#post-v1keyspacequery]

Query items

| Availability         | Source contract                                                  |
| -------------------- | ---------------------------------------------------------------- |
| Registration         | `config.enable_kv`                                               |
| 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. Handler additionally checks require(CoreAction::Query, Some(\&keyspace)).

### Request [#request-10]

**Path** — `String`

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

**Json** — `QueryRequest`

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

```rust
struct QueryRequest {
    filter: String,
    limit: Option<usize>,
    offset: Option<usize>,
}
```

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

### 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 query_items(
        Path(keyspace): Path<String>,
        State(state): State<AppState>,
        Extension(authority): Extension<RequestAuthority>,
        Extension(db): Extension<Arc<AkashaDB>>,
        Json(req): Json<QueryRequest>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        authority.require(CoreAction::Query, Some(&keyspace))?;
        let mut qb = db.query(&keyspace);
        if let Some(limit) = req.limit {
            qb = qb.limit(limit);
        }
        if let Some(offset) = req.offset {
            qb = qb.offset(offset);
        }
        // Simple filter language: field==value
        if !req.filter.is_empty()
            && let Some((field, value)) = req.filter.split_once("==")
        {
            qb = qb.filter(field.trim(), "==", value.trim());
        }
        let results = qb
            .execute()
            .await
            .map_err(|e| DaemonError::InvalidRequest(e.to_string()))?;
        Ok(Json(serde_json::json!({"rows": results})))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:4091`. Registration: `akasha-daemon/src/main.rs:4617`.

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

## GET `/v1/stats` [#get-v1stats]

Stats

| Availability         | Source contract                                                  |
| -------------------- | ---------------------------------------------------------------- |
| Registration         | `config.enable_kv`                                               |
| 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. Handler additionally checks require(CoreAction::Read, None).

### Request [#request-11]

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-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
s
```

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

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

Source: `akasha-daemon/src/main.rs:4120`. Registration: `akasha-daemon/src/main.rs:4618`.