Knowledge Namespaces

Knowledge namespaces are named containers for your AI knowledge contexts. They add a visibility layer so you can control which team members can access which knowledge bases.

Base path: /api/v1/accounts/{accountId}/knowledge-namespaces

Authentication: JWT Bearer token

---

Visibility Levels

Level	Who can access
private	Only the creator
workspace	All members of the associated workspace
account	All account members

---

List Namespaces

GET /accounts/{accountId}/knowledge-namespaces

Request

Path Parameter	Description
accountId	Account UUID

Query Parameter	Type	Description
workspaceId	uuid	Filter to a specific workspace

Response

Returns an array of namespace objects scoped to the account (optionally filtered to workspaceId).

Code Example

cURL

curl "https://api.chainabit.com/api/v1/accounts/$ACCOUNT_ID/knowledge-namespaces" \
  -H "Authorization: Bearer $TOKEN"

JavaScript

const response = await fetch(
  `${BASE_URL}/accounts/${accountId}/knowledge-namespaces`,
  { headers: { Authorization: `Bearer ${TOKEN}` } }
);
const { data } = await response.json();

Python

import httpx
result = httpx.get(
    f"{BASE_URL}/accounts/{account_id}/knowledge-namespaces",
    headers={"Authorization": f"Bearer {token}"},
).json()

---

Get Namespace

GET /accounts/{accountId}/knowledge-namespaces/{id}

Request

Path Parameter	Description
accountId	Account UUID
id	Namespace UUID

Response

Returns a single namespace object.

---

Create Namespace

POST /accounts/{accountId}/knowledge-namespaces

Requires owner or admin role.

Request

Path Parameter	Description
accountId	Account UUID

Request body:

Field	Type	Required	Description
name	string	Yes	Display name
slug	string	Yes	URL-safe identifier [a-z0-9-]+, unique per account
visibility	string	No	private | workspace | account (default: workspace)
workspaceId	uuid	No	Associate with a workspace
retentionDays	integer	No	Auto-purge TTL (1–3650 days)

Response

Returns the created namespace object.

Code Example

cURL

curl -X POST "https://api.chainabit.com/api/v1/accounts/$ACCOUNT_ID/knowledge-namespaces" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Engineering Docs",
    "slug": "engineering-docs",
    "visibility": "workspace",
    "retentionDays": 365
  }'

JavaScript

const response = await fetch(
  `${BASE_URL}/accounts/${accountId}/knowledge-namespaces`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'Engineering Docs',
      slug: 'engineering-docs',
      visibility: 'workspace',
      retentionDays: 365,
    }),
  }
);

Python

httpx.post(
    f"{BASE_URL}/accounts/{account_id}/knowledge-namespaces",
    json={
        "name": "Engineering Docs",
        "slug": "engineering-docs",
        "visibility": "workspace",
        "retentionDays": 365,
    },
    headers={"Authorization": f"Bearer {token}"},
)

---

Update Namespace

PATCH /accounts/{accountId}/knowledge-namespaces/{id}

Requires owner or admin role. Slug cannot be changed after creation.

Request

Path Parameter	Description
accountId	Account UUID
id	Namespace UUID

Request body: all fields optional

Field	Type	Description
name	string	New display name
visibility	string	private | workspace | account
retentionDays	integer or null	New retention TTL; null to remove

Response

Returns the updated namespace object.

---

Delete Namespace

DELETE /accounts/{accountId}/knowledge-namespaces/{id}

Soft-deletes the namespace. Requires owner or admin role. Associated contexts are not deleted.

Request

Path Parameter	Description
accountId	Account UUID
id	Namespace UUID

Response

Namespace is soft-deleted. Associated contexts are not deleted.

---

Errors

Status	Description
400	Invalid slug format (must match [a-z0-9-]+)
403	Caller does not have owner or admin role
404	Namespace not found
409	Slug already exists in this account