API reference

Knowledge bases

Upload a PDF or point at a URL so agents can answer from your documents.

A knowledge base is one document, a PDF file or a web page, that is split into chunks and indexed in the background. An agent uses a knowledge base by listing its vector_id in the agent configuration. During a call the agent retrieves the most relevant passages and answers from them. See the Knowledge bases guide.

All routes need Authorization: Bearer <key>. An unknown, deleted or foreign id answers 404 with Knowledgebase not found.

Operation	Method and path
Create a knowledge base	`POST /knowledgebase`
List knowledge bases	`GET /knowledgebase/all`
Get a knowledge base	`GET /knowledgebase/{rag_id}`
Delete a knowledge base	`DELETE /knowledgebase/{rag_id}`

Using a knowledge base in an agent

Put the vector_id values in the conversation task's language model configuration:

json

{
  "llm_agent": {
    "agent_type": "simple_llm_agent",
    "agent_flow_type": "streaming",
    "llm_config": {
      "provider": "openai",
      "model": "gpt-4o-mini",
      "vector_store": {
        "provider": "lancedb",
        "provider_config": {"vector_ids": ["c2a1f0de-5b6a-4c3d-9e8f-7a6b5c4d3e2f"]}
      }
    }
  }
}

A single id can also be given as provider_config.vector_id. An agent can only read knowledge bases of its own account.

Operations

Create a knowledge base

POST /knowledgebase

Creates a knowledge base from a PDF upload or a URL and starts ingestion. The response returns at once with status processing; poll Get a knowledge base until it is processed or error. The request is multipart/form-data.

Auth: API key or session token. Role: member and up.

Parameter	In	Type	Required	Description
`file`	form	file	one of `file` or `url`	A PDF of at most 25 MB. The content is checked, not the file name.
`url`	form	string	one of `file` or `url`	A web page to fetch. Private and internal addresses are refused by default.
`chunk_size`	form	integer	no	32 to 4096. Default `512`.
`similarity_top_k`	form	integer	no	1 to 50. Default `15`.
`overlapping`	form	integer	no	0 to `chunk_size` minus 1. Default `128`.
`language_support`	form	string	no	Only `multilingual` is accepted.

Request

bash

curl -X POST https://api.sevennadi.si/knowledgebase \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef" \
  -F "file=@policy-faq.pdf;type=application/pdf" \
  -F "chunk_size=512"

Response 200 OK

json

{
  "rag_id": "8e3f1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b",
  "file_name": "policy-faq.pdf",
  "source_type": "pdf",
  "status": "processing"
}

For a URL, file_name is the URL and source_type is url.

Errors

Status	Message
400	`Provide either file or url, not both` (also when neither is sent)
400	`chunk_size 32-4096, similarity_top_k 1-50, overlapping 0..chunk_size-1`
400	`language_support must be multilingual`
400	`Invalid url: <reason>`
400	`The PDF is larger than 25 MB`
400	`The file must be a PDF`
413	`The request body is larger than 26 MB`

List knowledge bases

GET /knowledgebase/all

Returns the account's knowledge bases, newest first. The list is not paginated.

Auth: API key or session token. Role: viewer and up.

No parameters.

Request

bash

curl https://api.sevennadi.si/knowledgebase/all \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef"

Response 200 OK

An array of knowledge base objects, each as in Get a knowledge base.

Get a knowledge base

GET /knowledgebase/{rag_id}

Returns one knowledge base with its ingestion status.

Auth: API key or session token. Role: viewer and up.

Parameter	In	Type	Required	Description
`rag_id`	path	string (UUID)	yes	The knowledge base.

Request

bash

curl https://api.sevennadi.si/knowledgebase/8e3f1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef"

Response 200 OK

json

{
  "rag_id": "8e3f1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b",
  "file_name": "policy-faq.pdf",
  "humanized_created_at": "2 minutes ago",
  "created_at": "2026-10-13T07:45:00Z",
  "updated_at": "2026-10-13T07:45:20Z",
  "vector_id": "c2a1f0de-5b6a-4c3d-9e8f-7a6b5c4d3e2f",
  "status": "processed",
  "source_type": "pdf",
  "chunk_size": 512,
  "similarity_top_k": 15,
  "overlapping": 128
}

status is processing, processed or error. When ingestion fails, an error field says why. language_support appears only when set.

Errors

Status	Message
404	`Knowledgebase not found`

Delete a knowledge base

DELETE /knowledgebase/{rag_id}

Deletes the knowledge base, its indexed chunks and the stored PDF. Agents that still list its vector_id simply get no passages from it.

Auth: API key or session token. Role: member and up.

Parameter	In	Type	Required	Description
`rag_id`	path	string (UUID)	yes	The knowledge base.

Request

bash

curl -X DELETE https://api.sevennadi.si/knowledgebase/8e3f1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef"

Response 200 OK

json

{"message": "success", "state": "deleted"}

Errors

Status	Message
404	`Knowledgebase not found`