# Cognitive Cycle

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

Source: https://docs.minds.sh/docs/api/instance/cognitive-cycle



This reference covers **7 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/cognitive/health`     | [Cognitive health](#get-v1-cognitive-health)         |
| `POST` | `/v1/cognitive/cycles`     | [Cognitive cycle trigger](#post-v1-cognitive-cycles) |
| `GET`  | `/v1/cognitive/cycles`     | [Cognitive cycle list](#get-v1-cognitive-cycles)     |
| `GET`  | `/v1/cognitive/cycles/:id` | [Cognitive cycle get](#get-v1-cognitive-cycles-id)   |
| `GET`  | `/v1/cognitive/config`     | [Cognitive config get](#get-v1-cognitive-config)     |
| `PUT`  | `/v1/cognitive/config`     | [Cognitive config update](#put-v1-cognitive-config)  |
| `GET`  | `/v1/cognitive/stats`      | [Cognitive stats](#get-v1-cognitive-stats)           |

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

## GET `/v1/cognitive/health` [#get-v1cognitivehealth]

Cognitive health

| Availability         | Source contract                            |
| -------------------- | ------------------------------------------ |
| Registration         | `always registered`                        |
| Runtime service      | `cognitive`                                |
| 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>`

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]

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

Source: `akasha-daemon/src/main.rs:10309`. Registration: `akasha-daemon/src/main.rs:4354`.

<a id="post-v1-cognitive-cycles" />

## POST `/v1/cognitive/cycles` [#post-v1cognitivecycles]

Cognitive cycle trigger

| Availability         | Source contract     |
| -------------------- | ------------------- |
| Registration         | `always registered` |
| Runtime service      | `cognitive`         |
| Handler dependencies | `Cognitive Cycle`   |

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

### Request [#request-1]

**Json** — `CognitiveRunCycleReq`

| Field     | Rust type           | Required on input         | Notes |
| --------- | ------------------- | ------------------------- | ----- |
| `input`   | `serde_json::Value` | Yes                       |       |
| `trigger` | `Option<String>`    | No; optional or defaulted |       |

```rust
struct CognitiveRunCycleReq {
    input: serde_json::Value,
    trigger: Option<String>,
}
```

### 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
cognitive_cycle_record_json(id, record)?
```

### 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 cognitive_cycle_trigger(
        State(state): State<AppState>,
        Extension(db): Extension<Arc<AkashaDB>>,
        Extension(authority): Extension<RequestAuthority>,
        Json(req): Json<CognitiveRunCycleReq>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        let namespace = cognitive_cycle_namespace(&db, &authority, CoreAction::Write)?;
        let dispatcher = require_service!(state.cognitive_cycle_dispatcher, "Cognitive Cycle");
        let (experience, trigger, input) = cognitive_cycle_experience(req)?;
        let started_at = Utc::now();
        let started = std::time::Instant::now();
        let (action, trace) = dispatcher.run_cycle(namespace, experience).await?;
        let completed_at = Utc::now();
        let duration_ms = started.elapsed().as_millis().min(u128::from(u64::MAX)) as u64;
        let record = CognitiveCycleRecord {
            schema_version: COGNITIVE_CYCLE_HISTORY_SCHEMA_VERSION,
            trigger,
            input,
            status: "completed".to_string(),
            started_at,
            completed_at,
            duration_ms,
            action,
            trace,
        };
        let id = persist_cognitive_cycle_record(&state, db, namespace, &record).await?;
        Ok(Json(cognitive_cycle_record_json(id, record)?))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:10618`. Registration: `akasha-daemon/src/main.rs:4374`.

<a id="get-v1-cognitive-cycles" />

## GET `/v1/cognitive/cycles` [#get-v1cognitivecycles]

Cognitive cycle list

| Availability         | Source contract     |
| -------------------- | ------------------- |
| Registration         | `always registered` |
| Runtime service      | `cognitive`         |
| Handler dependencies | `Cognitive Cycle`   |

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

### Request [#request-2]

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

### Response [#response-2]

**Declared return:** `Result<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!({
        "cycles": history.cycles,
        "total": total,
        "corruption": history.corruption,
    })
```

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

Directly referenced error variants: none in the handler body. Middleware and delegated services can return additional errors described in the shared error reference.

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

    ```rust
    async fn cognitive_cycle_list(
        State(state): State<AppState>,
        Extension(db): Extension<Arc<AkashaDB>>,
        Extension(authority): Extension<RequestAuthority>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        require_service!(state.cognitive_cycle_dispatcher, "Cognitive Cycle");
        cognitive_cycle_namespace(&db, &authority, CoreAction::Read)?;
        let history = load_cognitive_cycle_records(db).await?;
        let total = history.cycles.len();
        Ok(Json(serde_json::json!({
            "cycles": history.cycles,
            "total": total,
            "corruption": history.corruption,
        })))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:10648`. Registration: `akasha-daemon/src/main.rs:4374`.

<a id="get-v1-cognitive-cycles-id" />

## GET `/v1/cognitive/cycles/:id` [#get-v1cognitivecyclesid]

Cognitive cycle get

| Availability         | Source contract     |
| -------------------- | ------------------- |
| Registration         | `always registered` |
| Runtime service      | `cognitive`         |
| Handler dependencies | `Cognitive Cycle`   |

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

### 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
cognitive_cycle_record_json(id, record)?
```

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

Directly referenced error variants: `DataCorruption`, `Internal`, `InvalidRequest`, `NotFound`. 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 cognitive_cycle_get(
        State(state): State<AppState>,
        Extension(db): Extension<Arc<AkashaDB>>,
        Extension(authority): Extension<RequestAuthority>,
        Path(id): Path<String>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        require_service!(state.cognitive_cycle_dispatcher, "Cognitive Cycle");
        cognitive_cycle_namespace(&db, &authority, CoreAction::Read)?;
        Uuid::parse_str(&id)
            .map_err(|_| DaemonError::InvalidRequest("invalid cycle id".to_string()))?;
        ensure_cognitive_cycle_history(&db).await?;
        let record = db
            .get(COGNITIVE_CYCLE_HISTORY_KEYSPACE, &id)
            .await
            .map_err(|error| DaemonError::Internal(error.to_string()))?
            .ok_or_else(|| DaemonError::NotFound(format!("cycle {id} not found")))?;
        let record = decode_cognitive_cycle_record(record).map_err(|error| {
            DaemonError::DataCorruption(format!("cycle {id} history record is invalid: {error}"))
        })?;
        Ok(Json(cognitive_cycle_record_json(id, record)?))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:10665`. Registration: `akasha-daemon/src/main.rs:4378`.

<a id="get-v1-cognitive-config" />

## GET `/v1/cognitive/config` [#get-v1cognitiveconfig]

Cognitive config get

| Availability         | Source contract                            |
| -------------------- | ------------------------------------------ |
| Registration         | `always registered`                        |
| Runtime service      | `cognitive`                                |
| 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\_operator\_control().

### 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
cfg.clone()
```

### 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 cognitive_config_get(
        State(state): State<AppState>,
        Extension(authority): Extension<RequestAuthority>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        authority.require_operator_control()?;
        let cfg = state.cognitive_config.read().await;
        Ok(Json(cfg.clone()))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:10688`. Registration: `akasha-daemon/src/main.rs:4379`.

<a id="put-v1-cognitive-config" />

## PUT `/v1/cognitive/config` [#put-v1cognitiveconfig]

Cognitive config update

| Availability         | Source contract                            |
| -------------------- | ------------------------------------------ |
| Registration         | `always registered`                        |
| Runtime service      | `cognitive`                                |
| 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\_operator\_control().

### Request [#request-5]

**Json** — `serde_json::Value`

This handler accepts dynamic JSON. The field accesses below are source observations, not a fabricated required-field schema.

### 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!({"ok": true, "config": *cfg})
```

### 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 cognitive_config_update(
        State(state): State<AppState>,
        Extension(authority): Extension<RequestAuthority>,
        Json(body): Json<serde_json::Value>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        authority.require_operator_control()?;
        let mut cfg = state.cognitive_config.write().await;
        *cfg = body.clone();
        Ok(Json(serde_json::json!({"ok": true, "config": *cfg})))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:10698`. Registration: `akasha-daemon/src/main.rs:4379`.

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

## GET `/v1/cognitive/stats` [#get-v1cognitivestats]

Cognitive stats

| Availability         | Source contract     |
| -------------------- | ------------------- |
| Registration         | `always registered` |
| Runtime service      | `cognitive`         |
| Handler dependencies | `Cognitive Cycle`   |

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

### 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!({
        "totalCycles": total,
        "completedCycles": completed,
        "failedCycles": 0,
        "averageDurationMs": if completed == 0 {
            0
        } else {
            total_duration_ms / completed as u64
        },
        "lastCycleAt": history.cycles.first()
            .and_then(|c| c.get("completedAt"))
            .and_then(|v| v.as_str())
            .unwrap_or(""),
        "corruption": history.corruption,
    })
```

### 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 cognitive_stats(
        State(state): State<AppState>,
        Extension(db): Extension<Arc<AkashaDB>>,
        Extension(authority): Extension<RequestAuthority>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        require_service!(state.cognitive_cycle_dispatcher, "Cognitive Cycle");
        cognitive_cycle_namespace(&db, &authority, CoreAction::Read)?;
        let history = load_cognitive_cycle_records(db).await?;
        let total = history.cycles.len();
        let completed = history
            .cycles
            .iter()
            .filter(|c| c.get("status").and_then(|v| v.as_str()) == Some("completed"))
            .count();
        let total_duration_ms: u64 = history
            .cycles
            .iter()
            .filter_map(|cycle| cycle.get("durationMs").and_then(serde_json::Value::as_u64))
            .sum();
        Ok(Json(serde_json::json!({
            "totalCycles": total,
            "completedCycles": completed,
            "failedCycles": 0,
            "averageDurationMs": if completed == 0 {
                0
            } else {
                total_duration_ms / completed as u64
            },
            "lastCycleAt": history.cycles.first()
                .and_then(|c| c.get("completedAt"))
                .and_then(|v| v.as_str())
                .unwrap_or(""),
            "corruption": history.corruption,
        })))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:10710`. Registration: `akasha-daemon/src/main.rs:4383`.