List knowledge items

List folders and documents in a workspace knowledge location with supported filters.

Endpoint

GET/api/v1/workspaces/{workspace_id}/knowledge

Authentication

Operation class	Authentication	Minimum role	API key
dashboard-session-api	Dashboard session cookie; mutations also require X-CX-Request: 1.	member	Not allowed

Parameters

Name	In	Type	Required	Description
`workspace_id`	path	string	Yes	—
`folder_id`	query	string or null	No	—
`q`	query	string or null	No	—
`type`	query	string or null	No	—
`created_by`	query	string or null	No	—

Request body

This operation has no request body.

Example

curl --request GET 'https://operade.ai/api/v1/workspaces/ws_demo/knowledge' \
  --cookie 'cx_session=YOUR_SESSION_COOKIE'

Responses

Status	Description	Content
`4XX`	Handled client error	application/json: ErrorResponse
`200`	Successful Response	application/json: KnowledgeLibraryResponse

4XX application/json response schema

Field path	Type	Reference	Format	Nullable	Required	Enum	Description
`$`	object	ErrorResponse	—	No	Yes	—	—
`error`	object	ErrorItem	—	No	Yes	—	—
`error.code`	string	—	—	No	Yes	—	—
`error.details`	object	—	—	No	No	—	—
`error.message`	string	—	—	No	Yes	—	—

200 application/json response schema

Field path	Type	Reference	Format	Nullable	Required	Enum	Description
`$`	object	KnowledgeLibraryResponse	—	No	Yes	—	—
`breadcrumbs`	array<KnowledgeBreadcrumb>	—	—	No	Yes	—	—
`breadcrumbs[]`	object	KnowledgeBreadcrumb	—	No	Yes	—	—
`breadcrumbs[].id`	string	—	—	No	Yes	—	—
`breadcrumbs[].name`	string	—	—	No	Yes	—	—
`current_folder`	object or null	KnowledgeFolder	—	Yes	Yes	—	—
`current_folder.child_count`	integer	—	—	No	Yes	—	—
`current_folder.created_at`	string	—	date-time	No	Yes	—	—
`current_folder.created_by`	object	KnowledgeCreator	—	No	Yes	—	—
`current_folder.created_by.email`	string	—	—	No	Yes	—	—
`current_folder.created_by.id`	string	—	—	No	Yes	—	—
`current_folder.created_by.name`	string	—	—	No	Yes	—	—
`current_folder.entity_type`	string	—	—	No	Yes	"folder"	—
`current_folder.id`	string	—	—	No	Yes	—	—
`current_folder.name`	string	—	—	No	Yes	—	—
`current_folder.parent_folder_id`	string or null	—	—	Yes	Yes	—	—
`current_folder.updated_at`	string	—	date-time	No	Yes	—	—
`folder_tree`	array<KnowledgeFolderSummary>	—	—	No	Yes	—	—
`folder_tree[]`	object	KnowledgeFolderSummary	—	No	Yes	—	—
`folder_tree[].id`	string	—	—	No	Yes	—	—
`folder_tree[].name`	string	—	—	No	Yes	—	—
`folder_tree[].parent_folder_id`	string or null	—	—	Yes	Yes	—	—
`items`	array<object>	—	—	No	Yes	—	—
`items[]`	object	KnowledgeFolder or KnowledgeDocumentListItem	—	No	Yes	—	—
`items[].child_count`	integer	—	—	No	Yes	—	—
`items[].created_at`	string	—	date-time	No	Yes	—	—
`items[].created_by`	object	KnowledgeCreator	—	No	Yes	—	—
`items[].created_by.email`	string	—	—	No	Yes	—	—
`items[].created_by.id`	string	—	—	No	Yes	—	—
`items[].created_by.name`	string	—	—	No	Yes	—	—
`items[].entity_type`	string	—	—	No	Yes	"folder"	—
`items[].id`	string	—	—	No	Yes	—	—
`items[].name`	string	—	—	No	Yes	—	—
`items[].parent_folder_id`	string or null	—	—	Yes	Yes	—	—
`items[].updated_at`	string	—	date-time	No	Yes	—	—
`items[].byte_size`	integer	—	—	No	Yes	—	—
`items[].chunk_count`	integer	—	—	No	Yes	—	—
`items[].error`	string or null	—	—	Yes	Yes	—	—
`items[].folder_id`	string or null	—	—	Yes	Yes	—	—
`items[].indexed_at`	string or null	—	date-time	Yes	Yes	—	—
`items[].source_url`	string or null	—	—	Yes	Yes	—	—
`items[].status`	string	—	—	No	Yes	"pending", "indexing", "ready", "failed"	—
`items[].type`	string	—	—	No	Yes	"text", "file", "url"	—

Response example

{
  "items": [],
  "breadcrumbs": [],
  "current_folder": {
    "entity_type": "folder",
    "id": "string",
    "name": "string",
    "parent_folder_id": "string",
    "child_count": 0,
    "created_by": {
      "id": "string",
      "name": "string",
      "email": "string"
    },
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z"
  },
  "folder_tree": []
}

Errors

Reviewed common and route-declared errors are summarized here; the list is not exhaustive. Start with the distributed error index to find each code's canonical domain page.

Status	Code	Description
`401`	`unauthenticated`	Authentication is missing, invalid, or revoked.
`403`	`forbidden`	The authenticated caller does not have access to this operation.
`404`	`not_found`	The requested workspace resource was not found.