OpenMax
Free Trial

Apps API · Knowledge Bases

Knowledge Bases: 9 endpoints

← All groups

GET /api/v1/agents/{agent_member_id}/knowledge-bases

List the knowledge bases an Agent can read

Scope: kb:space:read · Called with: appToken · operationId: list-agent-knowledge-bases

Required app scope: kb:space:read.

Lists the knowledge bases the Agent can actually read (its owner's private knowledge base included, the Default knowledge base by its member rule), keeping only those the caller can read too. The others are not listed; their number is returned as hidden_count. The caller must be able to see the Agent: an unknown member is 404, an Agent of another org is 403, a member that is not an Agent is 400. Paged with limit/offset like list-kbs; pagination.total_count excludes hidden_count. Response wrapped in standard envelope.

Parameters

Name In Type Required Description
agent_member_id path string (uuid) yes Agent member UUID
limit query integer (int32) Items per page (default: 20, max: 100)
offset query integer (int32) Number of items to skip (default: 0)
status_filter query string: active, archived Filter by KB status (default: all non-trashed)

Responses

GET /api/v1/kbs

List KBs

Scope: kb:space:read · Called with: appToken · operationId: list-kbs

Required app scope: kb:space:read.

Returns knowledge bases. Response wrapped in standard envelope.

Parameters

Name In Type Required Description
limit query integer (int32) Items per page (default: 20, max: 100)
offset query integer (int32) Number of items to skip (default: 0)
status_filter query string: active, archived, trashed Filter by KB status

Responses

POST /api/v1/kbs

Create KB

Scope: kb:space:write · Called with: appToken · operationId: create-kb

Required app scope: kb:space:write.

Creates a knowledge base. visibility private creates a private knowledge base owned by the caller (the platform sets the owner): only a human member signed in directly may ask for it; Agents, services and delegated credentials (personal access tokens, workspace app tokens) get 400 KB_PRIVATE_VISIBILITY_RESERVED, and while system setting automation_private_scope_enabled is not "true" a human gets 403 PRIVATE_SCOPE_DISABLED (503 when the setting can't be read). Nothing is created when refused. open and closed are unchanged. Response wrapped in standard envelope.

Request body

application/json · CreateKBRequestBody

Field Type Required Description
description string KB description
icon string KB icon
name string yes KB name
visibility string: open, closed, private yes KB visibility

Responses

POST /api/v1/kbs/init

Initialize org KB

Scope: kb:space:write · Called with: appToken · operationId: init-org-kb

Required app scope: kb:space:write.

Initializes the organization knowledge base. Response wrapped in standard envelope.

Responses

DELETE /api/v1/kbs/{kb_id}

Delete KB

Scope: kb:space:delete · Called with: appToken · operationId: delete-kb

Required app scope: kb:space:delete.

Deletes a knowledge base. Needs kb.manage, as before, except that a private knowledge base can be deleted only by its owner (a caller without kb.manage gets 403 whether or not the knowledge base exists or is visible to it; one with kb.manage gets 404 for another member's private knowledge base), and not while projects (archived ones included) still use it: 409 KB_IN_USE_BY_PROJECTS with meta.project_count. Same rule as archive-kb. The platform still refuses deleting the personal knowledge base. Response wrapped in standard envelope.

Parameters

Name In Type Required Description
kb_id path string (uuid) yes KB UUID

Responses

GET /api/v1/kbs/{kb_id}

Get KB

Scope: kb:space:read · Called with: appToken · operationId: get-kb

Required app scope: kb:space:read.

Returns a knowledge base. Response wrapped in standard envelope.

Parameters

Name In Type Required Description
kb_id path string (uuid) yes KB UUID

Responses

PATCH /api/v1/kbs/{kb_id}

Update KB

Scope: kb:space:write · Called with: appToken · operationId: update-kb

Required app scope: kb:space:write.

Updates a knowledge base. Setting visibility to private, or changing the visibility of a private knowledge base, is refused with 412 KB_PRIVATE_VISIBILITY_IMMUTABLE and nothing is changed. Response wrapped in standard envelope.

Parameters

Name In Type Required Description
kb_id path string (uuid) yes KB UUID

Request body

application/json · UpdateKBRequestBody

Field Type Required Description
description string KB description
icon string KB icon
name string KB name
set_description boolean Set to true to apply description, or clear it when description is omitted
set_icon boolean Set to true to apply icon, or clear it when icon is omitted
visibility string: open, closed, private KB visibility

Responses

POST /api/v1/kbs/{kb_id}/archive

Archive KB

Scope: kb:space:write · Called with: appToken · operationId: archive-kb

Required app scope: kb:space:write.

Archives a knowledge base. Needs kb.manage, as before, except that a private knowledge base can be archived only by its owner (a caller without kb.manage gets 403 whether or not the knowledge base exists or is visible to it; one with kb.manage gets 404 for another member's private knowledge base), and not while projects (archived ones included) still use it: 409 KB_IN_USE_BY_PROJECTS with meta.project_count. Response wrapped in standard envelope.

Parameters

Name In Type Required Description
kb_id path string (uuid) yes KB UUID

Responses

POST /api/v1/kbs/{kb_id}/unarchive

Unarchive KB

Scope: kb:space:write · Called with: appToken · operationId: unarchive-kb

Required app scope: kb:space:write.

Unarchives a knowledge base. Response wrapped in standard envelope.

Parameters

Name In Type Required Description
kb_id path string (uuid) yes KB UUID

Responses