Categories
Categories API: 3 endpoints under /v1.
List semantic categories
GET /v1/categories/{workspaceId}
Returns the workspace's semantic categories, which decide which memory types consolidation promotes and which extraction instruction it uses. Requires the read permission.
See also: Consolidation, episodes and procedures.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
workspaceId (required) | path | string (uuid) | Workspace to act in. A workspace the credential cannot access returns 404. |
Responses
| Status | Description |
|---|---|
200 | A list of categories with name, description, promotable types, extraction prompt and enabled flag. |
Example
curl -X GET "$API/v1/categories/$WS" \
-H "Authorization: Bearer $KEY"Create or update a semantic category
POST /v1/categories/{workspaceId}
Creates a category, or updates the existing one when id is given. A category's extraction prompt only takes effect when an LLM is configured, and a per-call extractionInstructions on consolidation takes precedence over it. Requires the write permission.
See also: Consolidation, episodes and procedures.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
workspaceId (required) | path | string (uuid) | Workspace to act in. A workspace the credential cannot access returns 404. |
Request body (SemanticCategoryRequest)
| Field | Type | Description |
|---|---|---|
description | string | What the category covers. |
extractionPrompt | string | Extraction instruction for this category; only takes effect when an LLM is configured. |
id | string (uuid) | ID of the category to update; omit to create a new one. |
isEnabled | boolean | Whether the category is active; defaults to true. |
name | string | Category name. |
promotableTypes | array of string | Memory types this category promotes during consolidation. |
Responses
| Status | Description |
|---|---|
200 | The stored category. |
Response fields
| Field | Description |
|---|---|
id | Category ID; generated when the request did not include one. |
name | Category name. |
promotableTypes | Memory types this category promotes during consolidation. |
extractionPrompt | Extraction instruction used for this category, if any. |
isEnabled | Whether the category is active. |
Example
curl -X POST "$API/v1/categories/$WS" \
-H "Authorization: Bearer $KEY" \
-H 'Content-Type: application/json' \
-d '{"isEnabled":true}'Delete a semantic category
DELETE /v1/categories/{workspaceId}/{categoryId}
Deletes one semantic category from the workspace. The server answers 204 No Content on success. Requires the write permission.
See also: Consolidation, episodes and procedures.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
workspaceId (required) | path | string (uuid) | Workspace to act in. A workspace the credential cannot access returns 404. |
categoryId (required) | path | string (uuid) | ID of the semantic category. |
Responses
| Status | Description |
|---|---|
204 | No content |
Example
curl -X DELETE "$API/v1/categories/$WS/<categoryId>" \
-H "Authorization: Bearer $KEY"