Knowledge bases administered: llmgw ctl kb and /api/v1/kb

Collections made for an organization, team, project or person, their
dimension asked of the embedding model; granted and revoked by path, never
outside their organization; their documents listed and removed; and a search
an operator can try. In the OpenAPI document.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Ilker ManapandClaude Opus 5.5 committed 2026-10-08 13:49:44 +02:00
1 parent ffab3c99e3
commit 6466f37d50
8 files changed
+1405 -1

No files matched your search

+528
View File
@@ -53,6 +53,9 @@
{
"name": "jobs"
},
{
"name": "kb"
},
{
"name": "metrics"
},
@@ -1069,6 +1072,338 @@
}
}
},
"/api/v1/kb": {
"get": {
"operationId": "getKb",
"summary": "Every knowledge-base collection, with its documents' count and grants",
"description": "Says why there are none when the store cannot hold them (SQLite, or PostgreSQL without pgvector).",
"tags": [
"kb"
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KBView"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"default": {
"$ref": "#/components/responses/Error"
}
}
}
},
"/api/v1/kb/collections": {
"post": {
"operationId": "postKbCollections",
"summary": "Make a collection, owned by an organization, team, project or person",
"description": "The embedding model's dimension is asked of the model when dims is not given, so the model must be able to serve.",
"tags": [
"kb"
],
"parameters": [
{
"$ref": "#/components/parameters/Actor"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KBCreateRequest"
}
}
}
},
"responses": {
"201": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KBCollectionView"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"default": {
"$ref": "#/components/responses/Error"
}
}
}
},
"/api/v1/kb/collections/{id}": {
"delete": {
"operationId": "deleteKbCollectionsId",
"summary": "Remove a collection with its documents and grants",
"tags": [
"kb"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The collection's ID, its name when that is unique, or ORG/NAME.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/Actor"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": {}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"default": {
"$ref": "#/components/responses/Error"
}
}
}
},
"/api/v1/kb/collections/{id}/documents": {
"get": {
"operationId": "getKbCollectionsIdDocuments",
"summary": "A collection's documents",
"tags": [
"kb"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The collection's ID, its name when that is unique, or ORG/NAME.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/KBDocumentView"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"default": {
"$ref": "#/components/responses/Error"
}
}
},
"delete": {
"operationId": "deleteKbCollectionsIdDocuments",
"summary": "Remove one document from a collection",
"tags": [
"kb"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The collection's ID, its name when that is unique, or ORG/NAME.",
"schema": {
"type": "string"
}
},
{
"name": "name",
"in": "query",
"required": true,
"description": "The document's name, as listed.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/Actor"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": {}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"default": {
"$ref": "#/components/responses/Error"
}
}
}
},
"/api/v1/kb/grants": {
"post": {
"operationId": "postKbGrants",
"summary": "Let a scope, and everything below it, read or write a collection",
"description": "Never outside the collection's organization.",
"tags": [
"kb"
],
"parameters": [
{
"$ref": "#/components/parameters/Actor"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KBGrantRequest"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KBGrantView"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"default": {
"$ref": "#/components/responses/Error"
}
}
},
"delete": {
"operationId": "deleteKbGrants",
"summary": "Take a grant away",
"tags": [
"kb"
],
"parameters": [
{
"$ref": "#/components/parameters/Actor"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KBGrantRequest"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KBGrantView"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"default": {
"$ref": "#/components/responses/Error"
}
}
}
},
"/api/v1/kb/search": {
"post": {
"operationId": "postKbSearch",
"summary": "Try a search of a collection, as an administrator",
"description": "No tenancy applies: this is for checking what a collection holds and finds.",
"tags": [
"kb"
],
"parameters": [
{
"$ref": "#/components/parameters/Actor"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KBSearchRequest"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/KBHitView"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"default": {
"$ref": "#/components/responses/Error"
}
}
}
},
"/api/v1/metrics/range": {
"post": {
"operationId": "postMetricsRange",
@@ -4606,6 +4941,199 @@
}
}
},
"KBCollectionView": {
"type": "object",
"description": "KBCollectionView is a collection as an administrator sees it.",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"org": {
"type": "string"
},
"org_name": {
"type": "string"
},
"owner": {
"type": "string"
},
"owner_name": {
"type": "string"
},
"embed_model": {
"type": "string"
},
"dims": {
"type": "integer"
},
"documents": {
"type": "integer"
},
"chunks": {
"type": "integer"
},
"grants": {
"type": "array",
"items": {
"$ref": "#/components/schemas/KBGrantView"
},
"description": "Grants are who else may read or write it."
},
"created_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"type": "string"
}
}
},
"KBCreateRequest": {
"type": "object",
"description": "KBCreateRequest makes a collection.",
"properties": {
"owner": {
"type": "string",
"description": "Owner is org:NAME, team:ORG/TEAM, project:ORG/TEAM/PROJECT (or the ID after the colon), or user:USER-ID."
},
"org": {
"type": "string",
"description": "Org is the organization a person's collection belongs to; only for user: owners."
},
"name": {
"type": "string"
},
"model": {
"type": "string",
"description": "Model is the catalog model that embeds its documents."
},
"dims": {
"type": "integer",
"description": "Dims is the model's embedding dimension; asked of the model when 0."
}
}
},
"KBDocumentView": {
"type": "object",
"description": "KBDocumentView is one document in a collection.",
"properties": {
"name": {
"type": "string"
},
"digest": {
"type": "string"
},
"bytes": {
"type": "integer",
"format": "int64"
},
"chunks": {
"type": "integer"
},
"added_at": {
"type": "string",
"format": "date-time"
},
"added_by": {
"type": "string"
}
}
},
"KBGrantRequest": {
"type": "object",
"description": "KBGrantRequest lets a scope read or write a collection, or with DELETE takes that away.",
"properties": {
"collection": {
"type": "string",
"description": "Collection is its ID, its name when that is unique, or ORG/NAME."
},
"target": {
"type": "string",
"description": "Target is org:, team:, project:, key: or user: as for guard policies."
},
"perm": {
"type": "string",
"description": "Perm is read or write; ignored by DELETE."
}
}
},
"KBGrantView": {
"type": "object",
"description": "KBGrantView is one grant.",
"properties": {
"target": {
"type": "string"
},
"name": {
"type": "string"
},
"perm": {
"type": "string"
},
"at": {
"type": "string",
"format": "date-time"
},
"by": {
"type": "string"
}
}
},
"KBHitView": {
"type": "object",
"description": "KBHitView is one chunk a search found.",
"properties": {
"document": {
"type": "string"
},
"ord": {
"type": "integer"
},
"score": {
"type": "number"
},
"text": {
"type": "string"
}
}
},
"KBSearchRequest": {
"type": "object",
"description": "KBSearchRequest tries a search, as an administrator: no tenancy applies.",
"properties": {
"collection": {
"type": "string"
},
"query": {
"type": "string"
},
"k": {
"type": "integer"
}
}
},
"KBView": {
"type": "object",
"description": "KBView is every collection, or why there can be none.",
"properties": {
"available": {
"type": "boolean"
},
"reason": {
"type": "string",
"description": "Reason is why not, when not."
},
"collections": {
"type": "array",
"items": {
"$ref": "#/components/schemas/KBCollectionView"
}
}
}
},
"Live": {
"type": "object",
"description": "Live is one of the cluster's adapters as its node last reported it.",