---
title: "List retrieval namespaces"
method: GET
path: "/v1/projects/{project_id}/retrieval/namespaces"
tags: ["retrieval"]
---

# List retrieval namespaces

`GET /v1/projects/{project_id}/retrieval/namespaces`

## Request

- Base URL: `https://api.connic.co`
- URL: `https://api.connic.co/v1/projects/{project_id}/retrieval/namespaces`
- Auth: HTTP bearer

Returns the namespace hierarchy for managed retrieval. Namespaces use dot-separated paths (e.g. `docs.api`, `docs.guides`). Use `parent` to list children of a specific namespace and `depth` to control nesting. Without `parent`, the response's `parent` is null and `namespaces` holds the top-level namespaces.

Required permission: `retrieval.manage`.

## Path parameters

- `project_id` string, uuid, required

## Query parameters

- `environment_id` string, uuid, required: Environment ID from `GET /environments`.
- `parent` string, nullable: List the namespaces below this one, such as `docs`. The response's `parent` then describes it.
- `depth` integer: Levels to return: 1 returns only the direct children of `parent` (or the top level), 0 returns all levels.

## Response `200`

Successful Response

- PublicNamespacesResponse
  - `parent` PublicNamespaceResponse, required
    - `name` string, required: Full dot-separated namespace path, such as `docs.api`.
    - `entry_count` integer, required: Entries stored directly in this namespace.
    - `chunk_count` integer, required: Chunks stored directly in this namespace.
    - `total_entry_count` integer, required: Entries in this namespace and all of its descendants.
    - `has_children` boolean, required: Whether the namespace has child namespaces.
  - `namespaces` PublicNamespaceResponse[], required: Children of `parent`, or top-level namespaces without it, down to `depth` levels and sorted by name.
    - `name` string, required: Full dot-separated namespace path, such as `docs.api`.
    - `entry_count` integer, required: Entries stored directly in this namespace.
    - `chunk_count` integer, required: Chunks stored directly in this namespace.
    - `total_entry_count` integer, required: Entries in this namespace and all of its descendants.
    - `has_children` boolean, required: Whether the namespace has child namespaces.

## Other responses

- `401`: Missing or invalid API key.
- `403`: The API key lacks the required permission or access to the environment.
- `422`: Validation Error
- `429`: Rate limit exceeded.

---

[API](https://skmtc.dev/connic/apis/connic-api.md) · [All operations](https://skmtc.dev/connic/apis/connic-api/llms.txt) · [OpenAPI document](https://skmtc.dev/connic/apis/connic-api/revisions/482932da5fbe?raw)