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

# Namespaces & Keys

> Namespace-Isolation, Lifecycle-Zustände, gescopte cdb_-API-Keys mit Read-, Write- und Delete-Rechten, Per-Key-Rate-Limits und Metadaten-Endpunkte.

## Namespaces

Ein Namespace ist ein vollständig isolierter Store – mit eigenem WAL, Persister und Object-Store-Mirror. Namen sind 1–96 Zeichen aus `[a-z0-9_-]`, beginnen nicht mit `-` oder `_`, und liegen stets unter dem Präfix deines Accounts.

**Die Lifecycle-Semantik ist explizit:**

| Zustand                                 | Verhalten                                                                                                                                                                                                          |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Noch nie geschrieben                    | Lesevorgänge liefern `404 namespace_not_found` – nur Schreibvorgänge legen an                                                                                                                                      |
| Live                                    | Alle Operationen im Rahmen des Key-Scopes                                                                                                                                                                          |
| Beschäftigt / noch nicht mirror-durabel | Löschung liefert ein wiederholbares `409`                                                                                                                                                                          |
| Gelöscht                                | `410 namespace_deleted`, dauerhaft – ein durabler Tombstone wird lokal **und** auf den Mirror committet, bevor Daten entfernt werden, damit ein veraltetes Restore gelöschte Daten niemals wiederauferstehen lässt |

```bash theme={null}
# Inspizieren, ohne den Store zu öffnen
curl -s https://db.conare.ai/v1/namespaces/acme-docs/metadata \
  -H "Authorization: Bearer $CONAREDB_API_KEY"
# → { "name", "approx_row_count", "approx_logical_bytes", "generation", "dims", "index": {"status": "ann"} }

# Endgültige Löschung (erfordert die Delete-Berechtigung)
curl -s -X DELETE https://db.conare.ai/v1/namespaces/acme-docs \
  -H "Authorization: Bearer $DELETE_KEY"
```

## Keys

`cdb_...`-Bearer werden aus der [Console](https://db.conare.ai) bereitgestellt. Jeder Key hat:

* **Namespace-Scope** – exakte Namen oder trailing-`*`-Präfixe. Ein Key kann nur `/v1/namespaces/{name}/*` erreichen, wo der Name den Patterns entspricht; alles andere ergibt `403`.
* **Unabhängige Berechtigungen** – `read`, `write` und destruktives `delete` sind getrennte Grants. Physische Namespace-Löschung erfordert stets ein explizites `delete`.
* **Rate Limit** – ein Token-Bucket mit Anfragen pro Sekunde je Key, mit einer Sekunde Burst; überzogene Requests bekommen `429 rate_limited`.
* **Ablauf** – abgelaufene Keys liefern `401 expired_key`.

Secrets werden einmalig angezeigt und nur als SHA-256-Digest gespeichert; der Laufzeitvergleich ist konstantzeit.

<Warning>
  Gib einem alltäglichen Ingestion-Key kein `delete`. Nutze für destruktive Operationen ein separates kurzlebiges Credential und trenne Serving (Read-Only-Key) von Rebuild-Pipelines (Write-Key).
</Warning>

## Monitoring

| Endpunkt                          | Auth          | Zweck                                                                                                       |
| --------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------- |
| `GET /health`                     | keine         | Prozess-Liveness                                                                                            |
| `GET /ready`                      | keine         | Safe-to-serve; `503` beim Drainen oder nach einem Persister-Fehler – richte deinen Loadbalancer hierauf aus |
| `GET /v1/namespaces/{ns}/metrics` | gescopter Key | Laufzeitzähler deines Namespace                                                                             |
| `GET /v1/console`                 | gescopter Key | Maskierte Key-Metadaten, Nutzung und Metriken nur für deine Namespaces                                      |

Öffentliche Verfügbarkeit – geprüft aus fünf globalen Regionen gegen `https://db.conare.ai/ready` – wird auf [conare.betteruptime.com](https://conare.betteruptime.com/) veröffentlicht. API-Logs und Metriken enthalten niemals Request-Bodies oder Bearer-Tokens.