---
title: "Create a case (retention_mode REQUIRED, no default) · 2 credits"
method: POST
path: "/api/v1/cases"
tags: ["Cases"]
---

# Create a case (retention_mode REQUIRED, no default) · 2 credits

`POST /api/v1/cases`

## Request

- Base URL: `https://legal.nexusquantum.legal`
- URL: `https://legal.nexusquantum.legal/api/v1/cases`
- Auth: HTTP bearer

Opens a case (a persistent or ephemeral RAG workspace). 🔴 `retention_mode` is ALWAYS chosen explicitly (400 MISSING_RETENTION_MODE if absent): a `persistent` default would persist without permission and an `ephemeral` default would silently purge evidence — the only safe absence is not creating the case. Single debit here (2 cr `expediente_open`); the insert is rolled back if the debit fails. Supports Idempotency-Key (per-user encrypted cache). `pii_gatekeeper:"off"` requires account consent (403 PII_OPTOUT_NOT_ENABLED). Scope: cases | mcp | *.

## Request body

- CreateCaseRequest
  - `name` string, required: ZR recommendation: use your external matter ID, not personal data.
  - `retention_mode` 'persistent' | 'ephemeral', required: Lifecycle of the case SOURCE documents. REQUIRED, WITH NO DEFAULT, when creating through the API: `persistent` = sources are kept until explicitly deleted (firm archive); `ephemeral` = sources are PURGED when `ephemeral_ttl_hours` expires (sliding: reset on every ingest). The choice is audited (created_via=api). GDPR Art. 25 / Art. 5(1)(e).
  - `ephemeral_ttl_hours` integer: Only with ephemeral; with persistent → 400 TTL_WITHOUT_EPHEMERAL (never silently ignored).
  - `description` string
  - `jurisdiction` string: Optional (ISO). NEVER defaulted.
  - `pii_gatekeeper` 'on' | 'off'

## Response `201`

{ case: Case, inbound_alias, credits_charged: 2 }

## Other responses

- `400`: MISSING_RETENTION_MODE | INVALID_RETENTION_MODE | INVALID_TTL | TTL_WITHOUT_EPHEMERAL | INVALID_NAME
- `402`: INSUFFICIENT_CREDITS | SPEND_CAP_REACHED (monthly cap for the key)
- `403`: PII_OPTOUT_NOT_ENABLED (pii_gatekeeper off without consent) | INSUFFICIENT_SCOPE
- `409`: CASE_LIMIT_REACHED (50 active cases — a resource limit, not a rate limit)

---

[API](https://skmtc.dev/nexusquantum/apis/nexus-legal-api.md) · [All operations](https://skmtc.dev/nexusquantum/apis/nexus-legal-api/llms.txt) · [OpenAPI document](https://skmtc.dev/nexusquantum/apis/nexus-legal-api/revisions/4084d8d4eb0b?raw)