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

> List, create and delete namespaces.

A namespace is a named set of documents, like `docs` or `user-42`. Every write names one, and the
first write creates it. Give each of your users their own namespace to keep their data apart.

## List namespaces

`GET /namespaces`

Returns the namespaces that hold documents, in name order.

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.conare.ai/namespaces?prefix=user-" \
    -H "Authorization: Bearer $CONARE_API_KEY"
  ```

  ```ts TypeScript theme={null}
  await conare.namespaces({ prefix: "user-" });
  ```
</CodeGroup>

```json Response theme={null}
{ "namespaces": [{ "name": "user-42", "documents": 120 }] }
```

### Request

* `prefix` (string): Only namespaces whose names start with this.

## Create a namespace

`POST /namespaces`

Only needed for a namespace with a [sparse index](#sparse-index). Create it before its first write.

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.conare.ai/namespaces \
    -H "Authorization: Bearer $CONARE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"name": "web", "sparse": true}'
  ```

  ```ts TypeScript theme={null}
  await conare.namespace("web").create({ sparse: true });
  ```
</CodeGroup>

```json Response theme={null}
{ "name": "web", "sparse": true }
```

### Request

* `name` (string, required): 1-64 characters of `a-z 0-9 _ -`, starting with a letter or digit.
* `sparse` (boolean, default `false`): Give the namespace a sparse index.

### Sparse index

A sparse index lets queries use the `sparse` [retriever](/query#retrievers), which also matches
words related to the query's. Writes to a sparse namespace are slower.

A namespace's index is fixed: creating an existing namespace with the other setting returns
`409 conflict`. To switch, create a new namespace with the other setting and write your documents
to it.

## Delete a namespace

`DELETE /namespaces/:namespace`

Deletes the namespace and all its documents. This can't be undone. The name can be used again
right away.

<CodeGroup>
  ```bash curl theme={null}
  curl -X DELETE https://api.conare.ai/namespaces/docs \
    -H "Authorization: Bearer $CONARE_API_KEY"
  ```

  ```ts TypeScript theme={null}
  await conare.namespace("docs").drop();
  ```
</CodeGroup>

```json Response theme={null}
{ "deleted": true }
```

* Deleting it again also returns `{"deleted": true}`. A name that was never written returns
  `404 namespace_not_found`.
* Delete its [sources](/sources) first, or their next sync writes the namespace again.


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