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

# Safe House API Reference

> Complete reference for all Safe House endpoints — configuration, quarantine management, observability, pattern library, canary credentials, and compliance.

# Safe House API reference

The Safe House API covers six functional areas: configuration, quarantine management, observability and metrics, pattern and intelligence management, canary credentials, and compliance exports. All endpoints require a Bearer token or API key unless otherwise noted.

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

***

## Configuration

Safe House behavior is configured through the **protection card** — a per-agent manifest of mode, score thresholds, screened surfaces, and trusted sources, composed across platform → org → agent scopes. Control it globally for the org (via the org protection template), per-agent, or in bulk.

| Method  | Endpoint                                    | Description                                                                              |
| ------- | ------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `GET`   | `/v1/protection/org/:org_id`                | Retrieve the org-scope protection manifest — defaults inherited by all agents in the org |
| `PUT`   | `/v1/protection/org/:org_id`                | Replace the org-scope protection manifest                                                |
| `GET`   | `/v1/protection/agent/:agent_id`            | Retrieve the agent-scope protection manifest (this layer only)                           |
| `GET`   | `/v1/protection/agent/:agent_id/effective`  | Retrieve the composed, effective config after inheritance from org/platform              |
| `PUT`   | `/v1/protection/agent/:agent_id`            | Replace the agent-scope protection manifest                                              |
| `PATCH` | `/v1/protection/agent/:agent_id/thresholds` | Patch just the agent's score thresholds (`warn` / `quarantine` / `block`)                |
| `POST`  | `/v1/safe-house/config/bulk-apply`          | Apply a config object to multiple agents at once                                         |

The granular sub-resource paths (`/mode`, `/thresholds`, `/screen_surfaces`, `/trusted_sources`) accept `PUT` or `PATCH` and exist at every scope (`/protection/agent/:id`, `/protection/org/:id`, `/protection/team/:id`, `/protection/platform/:id`).

**Retrieve the org-scope manifest:**

```bash theme={null}
curl https://api.mnemom.ai/v1/protection/org/org-7f3a9b2c \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "card_version": "protection/2026-04-26",
  "agent_id": "*",
  "mode": "enforce",
  "thresholds": {
    "warn": 0.60,
    "quarantine": 0.80,
    "block": 0.95
  },
  "screen_surfaces": {
    "incoming": true,
    "outgoing": true,
    "tool_calls": true,
    "tool_responses": true
  },
  "trusted_sources": {
    "domains": [],
    "agent_ids": [],
    "ip_ranges": []
  }
}
```

**Update a single agent's thresholds:**

```bash theme={null}
curl -X PATCH https://api.mnemom.ai/v1/protection/agent/mnm-550e8400-e29b-41d4-a716-446655440000/thresholds \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "warn": 0.50,
    "quarantine": 0.70,
    "block": 0.88
  }'
```

To replace the whole agent-scope manifest, `PUT /v1/protection/agent/:agent_id` with a full [protection card](/concepts/protection-card).

**Bulk-apply a config to many agents:**

```bash theme={null}
curl -X POST https://api.mnemom.ai/v1/safe-house/config/bulk-apply \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_ids": ["mnm-550e8400-e29b-41d4-a716-446655440000", "mnm-0b3f2a1c-d4e5-4f60-b7a8-9c0d1e2f3a4b"],
    "config": {
      "mode": "enforce"
    }
  }'
```

***

## Quarantine management

Quarantined turns are held pending human review. Reviewers can release (with or without a false-positive flag) or confirm as a genuine threat.

| Method   | Endpoint                                | Description                                                                        |
| -------- | --------------------------------------- | ---------------------------------------------------------------------------------- |
| `GET`    | `/v1/safe-house/quarantine`             | List quarantined items — filter by `status`, `agent_id`, `threat_type`, date range |
| `GET`    | `/v1/safe-house/quarantine/:id`         | Retrieve a single quarantine record with full evaluation detail                    |
| `DELETE` | `/v1/safe-house/quarantine/:id`         | Delete a quarantine record (admin only; irreversible)                              |
| `POST`   | `/v1/safe-house/quarantine/:id/release` | Release the quarantined turn to the agent; optionally mark as false positive       |
| `POST`   | `/v1/safe-house/quarantine/:id/report`  | Confirm the quarantined turn as a genuine threat                                   |

**List open quarantine items:**

```bash theme={null}
curl "https://api.mnemom.ai/v1/safe-house/quarantine?status=pending&limit=20" \
  -H "Authorization: Bearer $TOKEN"
```

**Release with false-positive flag:**

```bash theme={null}
curl -X POST https://api.mnemom.ai/v1/safe-house/quarantine/qid_7f3a9b2c/release \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "is_false_positive": true,
    "note": "Verified legitimate wire transfer request from CFO"
  }'
```

**Confirm as genuine threat:**

```bash theme={null}
curl -X POST https://api.mnemom.ai/v1/safe-house/quarantine/qid_7f3a9b2c/report \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "note": "Confirmed BEC attempt — forwarded to security team"
  }'
```

***

## Query & observability

Query the full evaluation history, aggregate metrics, and access a live SSE stream for real-time monitoring.

| Method | Endpoint                            | Description                                                                                    |
| ------ | ----------------------------------- | ---------------------------------------------------------------------------------------------- |
| `GET`  | `/v1/safe-house/evaluations`        | Full evaluation log — filter by `agent_id`, `verdict`, `threat_type`, `from`, `to`, `min_risk` |
| `GET`  | `/v1/safe-house/metrics/summary`    | Aggregated counts: total evaluations, block rate, warn rate, false positive rate               |
| `GET`  | `/v1/safe-house/metrics/timeseries` | Time-bucketed metrics for charts — specify `bucket` (`hour`, `day`, `week`)                    |
| `GET`  | `/v1/safe-house/metrics/threats`    | Top threat types by volume and confidence over a time window                                   |
| `GET`  | `/v1/safe-house/feed`               | SSE stream of live Safe House events — connect once and receive events as they happen          |
| `GET`  | `/v1/safe-house/sessions`           | List active sessions with elevated session risk (`medium` or `high`)                           |

**Query evaluations with filters:**

```bash theme={null}
curl "https://api.mnemom.ai/v1/safe-house/evaluations?agent_id=mnm-550e8400-e29b-41d4-a716-446655440000&verdict=block&from=2026-03-01T00:00:00Z&limit=50" \
  -H "Authorization: Bearer $TOKEN"
```

**Get summary metrics:**

```bash theme={null}
curl "https://api.mnemom.ai/v1/safe-house/metrics/summary?from=2026-03-01T00:00:00Z&to=2026-03-30T23:59:59Z" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "period": { "from": "2026-03-01T00:00:00Z", "to": "2026-03-30T23:59:59Z" },
  "total_evaluations": 14832,
  "block_count": 47,
  "block_rate": 0.0032,
  "warn_count": 312,
  "warn_rate": 0.021,
  "quarantine_count": 89,
  "false_positive_count": 12,
  "false_positive_rate": 0.135,
  "top_threat_type": "prompt_injection"
}
```

**Connect to the live SSE feed:**

```bash theme={null}
curl -N https://api.mnemom.ai/v1/safe-house/feed \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: text/event-stream"
```

The feed emits `safe_house.evaluation.*`, `safe_house.canary.*`, `safe_house.session.*`, and `safe_house.campaign.*` events as they occur. Reconnect with `Last-Event-ID` to replay missed events (replays up to 10 minutes back).

***

## Patterns & intelligence

Manage the threat pattern library and retrieve adaptive threshold recommendations.

| Method | Endpoint                               | Description                                                                   |
| ------ | -------------------------------------- | ----------------------------------------------------------------------------- |
| `GET`  | `/v1/safe-house/patterns`              | List active and candidate threat patterns — filter by `status`, `threat_type` |
| `POST` | `/v1/safe-house/patterns`              | Submit a candidate pattern for review and potential promotion                 |
| `GET`  | `/v1/safe-house/threshold-suggestions` | Adaptive threshold recommendations based on your false-positive and miss rate |

**List active patterns for a threat type:**

```bash theme={null}
curl "https://api.mnemom.ai/v1/safe-house/patterns?status=active&threat_type=bec_fraud" \
  -H "Authorization: Bearer $TOKEN"
```

**Get threshold suggestions:**

```bash theme={null}
curl https://api.mnemom.ai/v1/safe-house/threshold-suggestions \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "suggestions": [
    {
      "threat_type": "bec_fraud",
      "scope": "agent",
      "agent_id": "mnm-550e8400-e29b-41d4-a716-446655440000",
      "current_warn": 0.45,
      "suggested_warn": 0.55,
      "current_block": 0.80,
      "suggested_block": 0.88,
      "rationale": "False positive rate 18.4% over 30 days — above 15% target. Raise warn threshold to reduce noise.",
      "confidence": "high"
    }
  ]
}
```

**Submit a candidate pattern:**

```bash theme={null}
curl -X POST https://api.mnemom.ai/v1/safe-house/patterns \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "threat_type": "bec_fraud",
    "pattern": "(?i)urgent.*wire.*ceo|executive.*transfer.*now",
    "description": "CEO wire fraud variant with transposed urgency/authority order",
    "source": "user_submission"
  }'
```

Submitted patterns enter `candidate` status. The arena evaluation pipeline tests them against labeled benign and malicious message sets. Patterns that exceed precision/recall thresholds are promoted to `active`.

***

## Canary credentials

Canary credentials are honeypot API keys, tokens, or other secrets deliberately planted in the agent's context. If an attacker extracts and uses them, Safe House detects the use and fires a `safe_house.canary.triggered` event.

| Method | Endpoint                             | Description                                               |
| ------ | ------------------------------------ | --------------------------------------------------------- |
| `POST` | `/v1/safe-house/canaries`            | Create a canary credential and associate it with an agent |
| `GET`  | `/v1/safe-house/canaries?agent_id=`  | List canaries for an agent                                |
| `GET`  | `/v1/safe-house/canaries/:id/status` | Check whether a specific canary has been triggered        |

**Create a canary:**

```bash theme={null}
curl -X POST https://api.mnemom.ai/v1/safe-house/canaries \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "mnm-550e8400-e29b-41d4-a716-446655440000",
    "type": "api_key",
    "label": "Honeypot AWS key — do not use",
    "inject_into": "system_prompt"
  }'
```

```json theme={null}
{
  "canary_id": "can_f9e2a01b",
  "credential": "AKIAFAKE00HONEYPOT01",
  "type": "api_key",
  "agent_id": "mnm-550e8400-e29b-41d4-a716-446655440000",
  "status": "active",
  "triggered": false,
  "created_at": "2026-03-30T12:00:00Z"
}
```

The `credential` value is returned only at creation time. Safe House monitors for its appearance in outbound requests or inbound message content.

**Check canary status:**

```bash theme={null}
curl https://api.mnemom.ai/v1/safe-house/canaries/can_f9e2a01b/status \
  -H "Authorization: Bearer $TOKEN"
```

***

## Special endpoints

### Cross-Agent campaign detection

List detected attack campaigns — groups of related attacks targeting multiple agents from the same infrastructure.

```bash theme={null}
curl "https://api.mnemom.ai/v1/safe-house/campaigns?status=active" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "campaigns": [
    {
      "campaign_id": "camp_b3c9d4a1",
      "status": "active",
      "threat_type": "bec_fraud",
      "affected_agents": ["mnm-550e8400-e29b-41d4-a716-446655440000", "mnm-0b3f2a1c-d4e5-4f60-b7a8-9c0d1e2f3a4b"],
      "agent_count": 2,
      "first_seen": "2026-03-30T16:50:00Z",
      "last_seen": "2026-03-30T17:20:00Z",
      "similarity_score": 0.92
    }
  ]
}
```

### EU AI Act compliance export

Export Safe House evaluation data in EU AI Act Article 50 compliance format.

```bash theme={null}
curl "https://api.mnemom.ai/v1/compliance/safe-house-report?from=2026-01-01T00:00:00Z&to=2026-03-31T23:59:59Z" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"
```

Returns a structured compliance report covering all evaluation decisions, blocked/quarantined turns, false positive resolutions, and configuration change audit records within the requested window. Supports `Accept: text/csv` for spreadsheet-compatible export.

***

## Error responses

All Safe House endpoints return standard Mnemom error objects:

```json theme={null}
{
  "error": {
    "code": "not_found",
    "message": "Quarantine item not found",
    "details": {
      "quarantine_id": "qid_7f3a9b2c"
    }
  }
}
```

| HTTP Status | Meaning                                              |
| ----------- | ---------------------------------------------------- |
| `400`       | Invalid request body or parameters                   |
| `401`       | Missing or invalid authentication                    |
| `403`       | Insufficient permissions for the requested operation |
| `404`       | Resource not found                                   |
| `429`       | Rate limit exceeded                                  |
| `500`       | Internal server error                                |

***

## See also

* [Safe House Threat Model](/guides/safe-house-threat-model) — What each threat type means and how detection works
* [Safe House Webhooks](/guides/safe-house-webhooks) — React to Safe House events in real-time
* [Safe House Monitoring](/guides/safe-house-monitoring) — Security Observatory and alert management
* [Policy Overview](/api-reference/policy-overview) — Policy enforcement runs alongside Safe House