> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mnemom.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Intelligence API

> API reference for fault line analysis, risk forecasting, policy recommendations, and transaction guardrails

<Note>
  Part of **[CLPI](/concepts/clpi) Phase 3: Intelligence Layer**. The Intelligence API provides fault line analysis, risk forecasting, and policy recommendations.
</Note>

The Intelligence Layer provides analytical capabilities on top of the policy and reputation data. It identifies fault lines in team configurations, forecasts risks, recommends policies, and manages transaction-scoped guardrails.

**Base URL:** `https://api.mnemom.ai/v1`

***

## Authentication

All intelligence endpoints require API key authentication.

| Endpoint | Auth Required | Notes |
| - | - | - |
| `POST /v1/teams/fault-lines` | API key | Analyze team fault lines |
| `POST /v1/teams/forecast` | API key | Forecast team risks |
| `POST /v1/teams/recommend-policy` | API key | Generate policy recommendation |
| `POST /v1/transactions` | API key | Create transaction with guardrails |
| `GET /v1/transactions/{id}` | API key | Get transaction details |
| `DELETE /v1/transactions/{id}` | API key | Delete transaction |

**API key authentication:** Pass in the `Authorization` header:

```
Authorization: Bearer {api_key}
```

API keys can be created in your dashboard under Settings or via `POST /v1/api-keys`.

***

## Rate limits

| Endpoint | Rate Limit | Window |
| - | - | - |
| `POST /teams/fault-lines` | 10 requests | per minute |
| `POST /teams/forecast` | 10 requests | per minute |
| `POST /teams/recommend-policy` | 10 requests | per minute |
| Transaction endpoints | 30 requests | per minute |

Rate-limited responses return HTTP `429` with a `Retry-After` header.

<Note>
  LLM-powered endpoints (`recommend-policy`, `forecast`) have lower limits due to compute cost.
</Note>

***

## Endpoints

### `POST /v1/teams/fault-lines`

Analyze fault lines in a team's configuration -- value conflicts, capability gaps, and agent incompatibilities.

**Request body:**

```json theme={null}
{
  "team_id": "team-abc123"
}
```

| Field | Type | Required | Description |
| - | - | - | - |
| `team_id` | string | Yes | Team identifier |

**Response:** `200 OK`

```json theme={null}
{
  "team_id": "team-abc123",
  "analysis_id": "fl-def456",
  "coherence": { "...": "dimensional coherence vector — governance median, conflict-edge count, conscience/integrity invariants" },
  "fault_lines": [
    {
      "id": "fl-001",
      "value": "harm_prevention",
      "classification": "priority_mismatch",
      "severity": "medium",
      "agents_declaring": ["agent-a", "agent-b"],
      "agents_missing": ["agent-c"],
      "agents_conflicting": [],
      "impact_score": 0.65,
      "resolution_hint": "Add harm_prevention to agent-c's alignment card",
      "affects_capabilities": ["content_moderation"]
    }
  ],
  "alignments": [
    {
      "id": "al-abc123",
      "fault_line_ids": ["fl-001", "fl-002", "fl-003"],
      "minority_agents": ["agent-c"],
      "majority_agents": ["agent-a", "agent-b"],
      "alignment_score": 0.87,
      "severity": "high",
      "description": "3 fault lines consistently isolate agent-c from the team"
    }
  ],
  "summary": {
    "total": 3,
    "resolvable": 2,
    "priority_mismatch": 1,
    "incompatible": 0,
    "critical_count": 0
  }
}
```

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `team_id` | string | Team identifier |
| `analysis_id` | string | Unique identifier for this analysis (used as input to `/forecast`) |
| `coherence` | object | Dimensional team-coherence vector (governance median, conflict edges, conscience/integrity invariants). Replaces the deprecated scalar `fleet_score` |
| `fault_lines` | array | List of detected fault lines |
| `alignments` | array | List of structural fault line alignments (compound fault lines that consistently split the same agents) |
| `summary` | object | Aggregate counts by classification and severity |

**FaultLine object:**

| Field | Type | Description |
| - | - | - |
| `id` | string | Unique fault line identifier |
| `value` | string | The value or capability where the fault line exists |
| `classification` | string | Fault line classification (see below) |
| `severity` | string | Severity level: `low`, `medium`, `high`, or `critical` |
| `agents_declaring` | string\[] | Agents that declare this value |
| `agents_missing` | string\[] | Agents that are missing this value |
| `agents_conflicting` | string\[] | Agents with conflicting definitions of this value |
| `impact_score` | number | Estimated impact on team operations (0.0 -- 1.0) |
| `resolution_hint` | string | Suggested action to resolve the fault line |
| `affects_capabilities` | string\[] | Capabilities affected by this fault line |

**FaultLineClassification enum:**

| Value | Description |
| - | - |
| `resolvable` | The fault line can be automatically resolved by adjusting agent configurations |
| `priority_mismatch` | Agents have the same value but with different priority levels |
| `incompatible` | Agents have fundamentally conflicting values that cannot be automatically reconciled |
| `complementary` | Value divergence appears intentional given agent specializations — may be a feature of the team architecture |

**Severity levels:**

| Level | Description |
| - | - |
| `low` | Minor misalignment, unlikely to cause operational issues |
| `medium` | Moderate misalignment that may affect coordination under certain conditions |
| `high` | Significant misalignment that will likely cause issues in production |
| `critical` | Severe conflict that requires immediate resolution before deployment |

**Summary object:**

| Field | Type | Description |
| - | - | - |
| `total` | number | Total number of detected fault lines |
| `resolvable` | number | Count of `resolvable` fault lines |
| `priority_mismatch` | number | Count of `priority_mismatch` fault lines |
| `incompatible` | number | Count of `incompatible` fault lines |
| `critical_count` | number | Count of fault lines with `critical` severity |

**FaultLineAlignment object:**

| Field | Type | Description |
| - | - | - |
| `id` | string | Unique alignment identifier |
| `fault_line_ids` | string\[] | IDs of the individual fault lines that form this structural fault line |
| `minority_agents` | string\[] | Agents on the smaller side of the divide |
| `majority_agents` | string\[] | Agents on the larger side of the divide |
| `alignment_score` | number | Strength of the structural alignment (0.0 -- 1.0); higher means the same agents are consistently isolated across multiple fault lines |
| `severity` | string | Severity level: `low`, `medium`, `high`, or `critical` |
| `description` | string | Human-readable summary of the structural fault line |

<Note>
  The fault line analysis is grounded in the `checkFleetFaultLines` function from `@mnemom/agent-alignment-protocol`. The same analysis is reproducible locally without the API.
</Note>

**Error responses:**

| Status | Meaning |
| - | - |
| `404` | Team not found |

***

### `POST /v1/teams/forecast`

Forecast risks based on fault line analysis. Uses LLM analysis (Claude Haiku) to predict failure modes and their probabilities.

**Request body:**

```json theme={null}
{
  "team_id": "team-abc123",
  "fault_line_analysis_id": "fl-def456"
}
```

| Field | Type | Required | Description |
| - | - | - | - |
| `team_id` | string | Yes | Team identifier |
| `fault_line_analysis_id` | string | Yes | Analysis ID from a previous `/teams/fault-lines` call |

**Response:** `200 OK`

```json theme={null}
{
  "forecast_id": "fc-ghi789",
  "fault_line_analysis_id": "fl-def456",
  "failure_modes": [
    {
      "mode": "escalation_conflict",
      "description": "Agents A and B have conflicting escalation triggers for financial operations",
      "probability": 0.45,
      "severity": "high",
      "triggered_by": ["fl-001", "fl-002"],
      "affected_agents": ["agent-a", "agent-b"],
      "mitigation_available": true
    }
  ],
  "overall_risk_level": "medium",
  "confidence": 0.78
}
```

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `forecast_id` | string | Unique forecast identifier |
| `fault_line_analysis_id` | string | The analysis this forecast is based on |
| `failure_modes` | array | Predicted failure modes |
| `overall_risk_level` | string | Aggregate risk: `low`, `medium`, `high`, or `critical` |
| `confidence` | number | Model confidence in the forecast (0.0 -- 1.0) |

**FailureMode object:**

| Field | Type | Description |
| - | - | - |
| `mode` | string | Failure mode type (see below) |
| `description` | string | Human-readable description of the predicted failure |
| `probability` | number | Estimated probability of occurrence (0.0 -- 1.0) |
| `severity` | string | Severity if the failure occurs: `low`, `medium`, `high`, or `critical` |
| `triggered_by` | string\[] | Fault line IDs that contribute to this failure mode |
| `affected_agents` | string\[] | Agents that would be affected |
| `mitigation_available` | boolean | Whether a policy recommendation can address this failure mode |

**FailureMode types:**

| Type | Description |
| - | - |
| `escalation_conflict` | Two or more agents have conflicting escalation triggers or thresholds |
| `capability_gap` | A required capability is not covered by any agent in the team |
| `value_override` | An agent may override another agent's value constraints during coordination |
| `coordination_deadlock` | Agents may reach a deadlock state due to circular dependencies or conflicting preconditions |
| `trust_erosion` | Repeated misalignment may degrade trust scores over time |

**Error responses:**

| Status | Meaning |
| - | - |
| `404` | Team or analysis not found |

***

### `POST /v1/teams/recommend-policy`

Generate a policy recommendation based on team analysis. Uses LLM analysis to produce a policy that resolves detected fault lines and mitigates forecasted risks.

**Request body:**

```json theme={null}
{
  "team_id": "team-abc123"
}
```

| Field | Type | Required | Description |
| - | - | - | - |
| `team_id` | string | Yes | Team identifier |

**Response:** `200 OK`

```json theme={null}
{
  "recommendation_id": "rec-jkl012",
  "policy": { "..." : "..." },
  "reasoning_chain": [
    {
      "step": 1,
      "action": "Mapped browser tools to web_fetch capability",
      "rationale": "All team members use mcp__browser__* tools for research tasks",
      "fault_lines_addressed": ["fl-001"]
    }
  ],
  "confidence": 0.85,
  "forecast_summary": {
    "risk_reduction": "medium → low",
    "fault_lines_resolved": 2
  },
  "validation": {
    "valid": true,
    "errors": []
  }
}
```

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `recommendation_id` | string | Unique recommendation identifier |
| `policy` | object | The generated policy object, ready for use with the [Policy Management API](/api-reference/policy-overview) |
| `reasoning_chain` | array | Step-by-step reasoning for the policy recommendation |
| `confidence` | number | Model confidence in the recommendation (0.0 -- 1.0) |
| `forecast_summary` | object | Summary of how the recommended policy affects risk |
| `validation` | object | Whether the generated policy passes schema validation |

**ReasoningStep object:**

| Field | Type | Description |
| - | - | - |
| `step` | number | Step number in the reasoning chain |
| `action` | string | What the recommendation does at this step |
| `rationale` | string | Why this action was chosen |
| `fault_lines_addressed` | string\[] | Fault line IDs resolved by this step |

**ForecastSummary object:**

| Field | Type | Description |
| - | - | - |
| `risk_reduction` | string | Risk level change (e.g., `"medium → low"`) |
| `fault_lines_resolved` | number | Number of fault lines resolved by the recommendation |

**Validation object:**

| Field | Type | Description |
| - | - | - |
| `valid` | boolean | Whether the generated policy passes schema validation |
| `errors` | string\[] | Validation errors, if any |

**Error responses:**

| Status | Meaning |
| - | - |
| `404` | Team not found |

***

### `POST /v1/transactions`

Create a transaction with scoped guardrails. Transaction guardrails use a 3-layer merge: org + team + transaction policies with intersection semantics for `capability_mappings`.

**Request body:**

```json theme={null}
{
  "agent_id": "mnm-550e8400-e29b-41d4-a716-446655440000",
  "description": "Process customer refund",
  "action_type": "financial_operation",
  "tools": ["mcp__payment__refund", "mcp__db__update_order"],
  "duration_hours": 1,
  "policy": { "..." : "..." }
}
```

| Field | Type | Required | Description |
| - | - | - | - |
| `agent_id` | string | Yes | Agent performing the transaction |
| `description` | string | Yes | Human-readable description of the transaction |
| `action_type` | string | Yes | Category of the action (e.g., `financial_operation`, `data_access`, `content_generation`) |
| `tools` | string\[] | Yes | MCP tools the agent is authorized to use during this transaction |
| `duration_hours` | number | No | Transaction TTL in hours (default: 1, max: 24) |
| `policy` | object | No | Transaction-scoped policy overrides; merged with org and team policies |

**Response:** `200 OK`

```json theme={null}
{
  "transaction_id": "txn-mno345",
  "agent_id": "mnm-550e8400-e29b-41d4-a716-446655440000",
  "description": "Process customer refund",
  "action_type": "financial_operation",
  "status": "active",
  "tools": ["mcp__payment__refund", "mcp__db__update_order"],
  "merged_policy": { "..." : "..." },
  "created_at": "2026-02-26T10:00:00.000Z",
  "expires_at": "2026-02-26T11:00:00.000Z"
}
```

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `transaction_id` | string | Unique transaction identifier |
| `agent_id` | string | Agent performing the transaction |
| `description` | string | Transaction description |
| `action_type` | string | Action category |
| `status` | string | Transaction status: `active`, `completed`, or `expired` |
| `tools` | string\[] | Authorized tools for this transaction |
| `merged_policy` | object | The resolved policy after 3-layer merge (org + team + transaction) |
| `created_at` | string | ISO 8601 creation timestamp |
| `expires_at` | string | ISO 8601 expiry timestamp |

**Error responses:**

| Status | Meaning |
| - | - |
| `400` | Invalid request body or unsupported `action_type` |
| `404` | Agent not found |
| `409` | Conflicting concurrent transaction |

***

### `GET /v1/transactions/{id}`

Get transaction details including the resolved policy.

**Parameters:**

| Parameter | In | Type | Required | Description |
| - | - | - | - | - |
| `id` | path | string | Yes | Transaction identifier |

**Response:** `200 OK`

Returns the same transaction object as `POST /v1/transactions`.

**Error responses:**

| Status | Meaning |
| - | - |
| `404` | Transaction not found |

***

### `DELETE /v1/transactions/{id}`

Delete or cancel an active transaction. Expired transactions are automatically cleaned up and do not need to be deleted.

**Parameters:**

| Parameter | In | Type | Required | Description |
| - | - | - | - | - |
| `id` | path | string | Yes | Transaction identifier |

**Response:** `200 OK`

```json theme={null}
{ "deleted": true, "id": "txn-mno345" }
```

**Error responses:**

| Status | Meaning |
| - | - |
| `404` | Transaction not found |

***

## Error codes

Every intelligence endpoint can return `400` (invalid request), `401` (missing/invalid API
key), `404` (resource not found), `429` (rate limited — check `Retry-After`), or `500` (server
error, retry with backoff). `POST /teams/recommend-policy` and `POST /transactions` can also
return `409` on a conflicting concurrent request.

All error responses follow the standard envelope:

```json theme={null}
{
  "error": {
    "code": "not_found",
    "message": "Team not found"
  }
}
```

***

## SDK usage

<Note>
  The Intelligence endpoints are not yet wrapped by the `@mnemom/sdk` client (which currently covers the `agents` and `catalog` namespaces). Call them directly over HTTP until SDK helpers ship.
</Note>

<CodeGroup>
  ```typescript TypeScript theme={null}
  const API_BASE = 'https://api.mnemom.ai';
  const headers = {
    Authorization: `Bearer ${process.env.MNEMOM_API_KEY}`,
    'Content-Type': 'application/json',
  };

  // Analyze fault lines
  const analysis = await fetch(`${API_BASE}/v1/teams/fault-lines`, {
    method: 'POST',
    headers,
    body: JSON.stringify({ team_id: 'team-abc123' }),
  }).then((r) => r.json());
  console.log(`Fault lines: ${analysis.summary.total}`);

  // Forecast risks
  const forecast = await fetch(`${API_BASE}/v1/teams/forecast`, {
    method: 'POST',
    headers,
    body: JSON.stringify({
      team_id: 'team-abc123',
      fault_line_analysis_id: analysis.analysis_id,
    }),
  }).then((r) => r.json());
  console.log(`Risk level: ${forecast.overall_risk_level}`);

  // Generate policy recommendation
  const recommendation = await fetch(`${API_BASE}/v1/teams/recommend-policy`, {
    method: 'POST',
    headers,
    body: JSON.stringify({ team_id: 'team-abc123' }),
  }).then((r) => r.json());
  console.log(`Confidence: ${recommendation.confidence}`);
  console.log(`Fault lines resolved: ${recommendation.forecast_summary.fault_lines_resolved}`);

  // Create a transaction with guardrails
  const txn = await fetch(`${API_BASE}/v1/transactions`, {
    method: 'POST',
    headers,
    body: JSON.stringify({
      agent_id: 'mnm-550e8400-e29b-41d4-a716-446655440000',
      description: 'Process customer refund',
      action_type: 'financial_operation',
      tools: ['mcp__payment__refund', 'mcp__db__update_order'],
      duration_hours: 1,
    }),
  }).then((r) => r.json());
  console.log(`Transaction: ${txn.transaction_id}, expires: ${txn.expires_at}`);
  ```

  ```python Python theme={null}
  import httpx

  API_BASE = "https://api.mnemom.ai"
  headers = {"Authorization": f"Bearer {api_key}"}

  # Analyze fault lines
  analysis = httpx.post(
      f"{API_BASE}/v1/teams/fault-lines",
      headers=headers,
      json={"team_id": "team-abc123"},
  ).json()
  print(f"Fault lines: {analysis['summary']['total']}")

  # Forecast risks
  forecast = httpx.post(
      f"{API_BASE}/v1/teams/forecast",
      headers=headers,
      json={
          "team_id": "team-abc123",
          "fault_line_analysis_id": analysis["analysis_id"],
      },
  ).json()
  print(f"Risk level: {forecast['overall_risk_level']}")

  # Generate policy recommendation
  recommendation = httpx.post(
      f"{API_BASE}/v1/teams/recommend-policy",
      headers=headers,
      json={"team_id": "team-abc123"},
  ).json()
  print(f"Confidence: {recommendation['confidence']}")
  print(f"Risk reduction: {recommendation['forecast_summary']['risk_reduction']}")

  # Create a transaction with guardrails
  txn = httpx.post(
      f"{API_BASE}/v1/transactions",
      headers=headers,
      json={
          "agent_id": "mnm-550e8400-e29b-41d4-a716-446655440000",
          "description": "Process customer refund",
          "action_type": "financial_operation",
          "tools": ["mcp__payment__refund", "mcp__db__update_order"],
          "duration_hours": 1,
      },
  ).json()
  print(f"Transaction: {txn['transaction_id']}, expires: {txn['expires_at']}")
  ```
</CodeGroup>

***

## See also

* [Policy Engine](/concepts/policy-engine) -- Policy concepts
* [Team Reputation](/concepts/team-reputation) -- Team scoring
* [Policy Management](/guides/policy-management) -- Policy workflows
* [Risk Engine Guide](/guides/risk-engine) -- Risk assessment


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.