> ## 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 states, scoped cdb_ API keys with read, write, and delete permissions, per-key rate limits, and metadata endpoints.

## Namespaces

A namespace is a complete isolated store — its own WAL, persister, and object-store mirror. Names are 1–96 chars of `[a-z0-9_-]`, not starting with `-` or `_`, always under your account's prefix.

**Lifecycle semantics are explicit:**

| State                         | Behavior                                                                                                                                                                       |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Never written                 | Reads return `404 namespace_not_found` — only writes create                                                                                                                    |
| Live                          | All operations under your key's scope                                                                                                                                          |
| Busy / not yet mirror-durable | Deletion returns a retryable `409`                                                                                                                                             |
| Deleted                       | `410 namespace_deleted`, permanently — a durable tombstone is committed locally **and** to the mirror before data removal, so a stale restore can never resurrect deleted data |

```bash theme={null}
# Inspect without opening the store
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"} }

# Permanent deletion (requires the delete permission)
curl -s -X DELETE https://db.conare.ai/v1/namespaces/acme-docs \
  -H "Authorization: Bearer $DELETE_KEY"
```

## Keys

`cdb_...` bearers are provisioned from the [console](https://db.conare.ai). Each key has:

* **Namespace scope** — exact names or trailing-`*` prefixes. A key can only reach `/v1/namespaces/{name}/*` where the name matches its patterns; everything else is `403`.
* **Independent permissions** — `read`, `write`, and destructive `delete` are separate grants. Physical namespace deletion always requires an explicit `delete`.
* **Rate limit** — a per-key requests-per-second token bucket with one second's burst; over-limit requests get `429 rate_limited`.
* **Expiry** — expired keys return `401 expired_key`.

Secrets are shown once and stored only as SHA-256 digests; runtime comparison is constant-time.

<Warning>
  Don't grant `delete` to an everyday ingestion key. Use a separate short-lived credential for destructive operations, and split serving (read-only key) from rebuild pipelines (write key).
</Warning>

## Monitoring

| Endpoint                          | Auth       | Purpose                                                                                          |
| --------------------------------- | ---------- | ------------------------------------------------------------------------------------------------ |
| `GET /health`                     | none       | Process liveness                                                                                 |
| `GET /ready`                      | none       | Safe-to-serve; `503` while draining or after a persister failure — point your load balancer here |
| `GET /v1/namespaces/{ns}/metrics` | scoped key | Your namespace's runtime counters                                                                |
| `GET /v1/console`                 | scoped key | Masked key metadata, usage, and metrics for your namespaces only                                 |

Public availability — probed from five global regions against `https://db.conare.ai/ready` — is published at [conare.betteruptime.com](https://conare.betteruptime.com/). API logs and metrics never include request bodies or bearer tokens.