Knowledge Bases

Knowledge bases are collections of content sources that power AI agents with contextual information. They index content, generate vector embeddings, and provide intelligent retrieval capabilities.

What are Knowledge Bases?

A knowledge base is an organized collection of content sources that provides:

• Interactive Chat — Ask questions and have conversations with your indexed content using built-in RAG
• Vector Embeddings — AI-powered content representations for similarity matching
• Agent Context — Provide agents with relevant information automatically
• Content Triggers — Automatically run agents when content changes
• Multi-Source Indexing — Combine multiple sources into one searchable collection

Knowledge bases act as the "memory" for your AI agents, allowing them to access and reason about your content intelligently.

Creating a Knowledge Base

1. Navigate to the Knowledge Bases page
2. Click Create Knowledge Base
3. Give it a name and optional description
4. Select one or more content sources to include
5. Configure retrieval settings (or keep the defaults)

You can add or remove sources at any time after creation.

Retrieval Settings

Each knowledge base carries retrieval settings. They are not all the same kind of setting, and the difference decides whether changing one affects agents you have already built:

Reranker Model is inherited on every run. A retrieval step that leaves its own reranker unset uses whatever the knowledge base is set to, so changing it here changes how existing agents retrieve.

Building a knowledge base over the API instead? GET /models/rerankers and the list_reranker_models MCP tool list the available rerankers with their per-action credit cost and which one is the default. To turn reranking off, send "none" as reranker_model — that is not a value from the list.

Top N, Top K and Score Threshold are starting values, not live settings. When you pick this knowledge base on a new retrieval step, the editor fills these in for you — and from then on the step owns them. Changing them here never alters an agent you have already built, and never overwrites a value you set on a step yourself. Edit the step to change what a built agent retrieves.

Score Threshold filters on rerank scores only. It becomes the step's Minimum Rerank Score, which drops matches the reranker scored below it. It does nothing when reranking is off, and it never filters on similarity score — so it is not a general relevance cutoff. Matches a reranker cannot score, such as natively embedded images, are always kept.

A reranker is a text model — it scores your query text against each match's chunk text. Chunks indexed natively as images, audio or video carry no text, so a reranker has nothing to score for them — Seclai skips reranking automatically when a search turns up nothing it could score, and a retrieval step can override the knowledge base either way. A knowledge base is created with Reranker Model: None by default only when every one of its sources uses an embedding model that cannot handle text at all; a multi-modal model (the default) can index both, so it keeps the reranker for the text it holds. See Reranking and media knowledge bases.

Turning the reranker off over the API or MCP: send "none". reranker_model is three-valued on an update, and the three are easy to confuse. Omitting the field — or sending null — leaves the current reranker exactly as it is; it does not turn it off. Send the string "none" to turn reranking off, and a model id to switch to that model. The empty string is still accepted as a synonym for "none", but prefer "none": an empty string does not reliably survive every client's serialization, so it can arrive as nothing at all — which reads as "leave it unchanged".

Media Indexing

By default a content source indexes the text of the web pages it follows. You can also have a source attach the media in the main content of those pages to each page's item, so the knowledge base can retrieve images (and video) by content — not just the surrounding text. Each image or video that was attached is listed under the page's Attachments with its own indexing status and, when it could not be indexed, the reason.

Images covers documents too. On a website or RSS source, the Images choice also covers the images inside a PDF, Word, PowerPoint or Excel file (.docx, .pptx, .xlsx). A source that follows no web pages (uploads, a cloud drive, email) has Index images inside documents in its place, which is on for a new source until you clear it. Through the API and the update_source MCP tool the same holds: images in media_types on a website or RSS source, and document_images, on for a new source unless you send false, on every other. Below API version 2026-10-18, a source created without document_images on an embedding model that cannot index images has it off (see Changes by version). When it is on, and on a website or RSS source when its embedding model can index images, the images are extracted as the file is added or replaced, whether it was uploaded, pulled or attached to an email. Files already in the source are not revisited when you switch this on or change the source's embedding model: add a file again to have its images attached under the new setting. After it is switched off, documents added afterwards are indexed from their text alone, and images already attached stay. Each image becomes an attachment of the item: it is listed under the item's Attachments with its own indexing status, and is indexed the way an attached image is, by the image itself and by any text in it, or by its text alone on an embedding model that cannot index images. An image from a PDF carries its page number as page_number metadata: the attachment list shows it, a retrieval metadata filter can match it, and a search hit on the image has it in its metadata. On an embedding model that can index images, a page of drawings that contributed no picture of its own is attached as a render of the whole page, marked page_render: true in the same metadata. A render is indexed by the image alone: the page's text is indexed with the document, so labels a drawing stores as shapes and not as text are found through the image only. An image in a format the model does not accept, such as BMP or TIFF, is attached and indexed by any text in it; one with no text is listed as not searchable, with the reason. An image whose name is already taken by a file attached to the item is not attached. Each attached image is billed as an attached file is.

Choose media indexing per source when you create the source — it is on the media step — or turn it on later from the source's Edit dialog under Media indexing:

It applies to pages fetched after it is switched on; a page already in the source gains its media when its text next changes.

Files a feed item carries are a separate choice. An RSS item can list files beside its content. A source attaches the kinds you choose, and none until you choose:

Choose them on the Media & files step when you create an RSS source, where a preview shows what the feed's latest items carry with each part labelled, or later from the source's Edit dialog, the API or the update_source MCP tool. Each file becomes an attachment of the item and is indexed and billed as a file mailed to an email source is: a PDF by its text, and by the images inside it when Images is chosen, an image by the image and any text in it. At most 25 files are read from one item, across all kinds. A download that fails because the host is unreachable or busy is tried again later. A file larger than 25 MB, or one that could not be downloaded, is listed as a failed attachment with the reason. Each is named by its kind, as in enclosures/notes.pdf, so it never takes the name of an image from the item's web page. The choice applies to items added after it is made.

Vector-drawn PDF pages are attached as page images. Assembly instructions, schematics, exploded parts diagrams and CAD exports are drawn as vector art rather than embedded photographs, so there is no image inside them to pull out. On an embedding model that can index images, for any page that contains no embedded image of its own, Seclai renders the page and attaches the render as an image — so a search of the PDF's images returns the pictures rather than nothing. Four things follow from that:

• It works page by page, not document by document. A manual whose cover page carries a bitmap logo still gets its illustration pages rendered; the cover contributes its logo, the rest contribute their pages.
• A page that already has an embedded image is not also rendered, so the same picture is never attached — or billed — twice.
• Text-only pages are skipped. A page has to actually draw something to be rendered; pages that are just prose are left to the text index, so you are not billed for an embedding of a picture of text.
• A rendered page's attachment is named after the page (page_7.png, versus page_7_image_0.png for an image the PDF genuinely contained) and carries its page number like any other PDF image.

There is no page limit. A 400-page manual has every one of its illustrated pages attached. Extraction runs in the background once the item itself is indexed and continues across as many passes as the document needs, so the images appear under the item's Attachments, and become searchable, after its text does. You are billed for each image that is attached.

The count is per source. It is the number of images and video attached to the item on this source. Another source that ingests the same web page has its own attachments and its own count.

Checking what was indexed. For a web page, open the content item and look next to the word count: it reads "12 embedded images/videos indexed". Nothing is shown there when media indexing did not apply to the page or found nothing in it. The same value is on GET /contents/{id} as extracted_media_count and on the get_source_content_text MCP tool, where those cases are null. For a PDF, Word, PowerPoint or Excel file, the same count is the number of images attached from inside it. In both cases each one is under the item's Attachments, listed with its own indexing status, and its page for a PDF. The app shows the first 100 attachments of an item; GET /contents/{id}/attachments pages through all of them.

Requires a multi-modal embedder. Media on a web page is only retrievable if the knowledge base's embedding model can index that modality. Most multi-modal embedders support images; video requires a video-capable embedder (e.g. Nova Multimodal). The Edit dialog only offers the media kinds your embedder can index (others are hidden), and any unsupported kind is dropped at index time — so enabling Video on a text/image-only KB is a no-op rather than an error. Audio and linked documents are not offered here because this setting is about pulling media out of a page — there are no pictures inside an MP3, and a PDF's pictures follow Images, as described above.

Uploaded files are embedded whole, separately from this setting. On a multi-modal embedder, an uploaded image, video or audio file gets one embedding of the file itself in place of its extracted text, which is kept as the item's text but not indexed — which is what makes a photograph findable by a photo, and an audio file findable by a sound. That happens for any source whose embedder can read the file's format, with no toggle, and each such embedding is billed at the embedder's rate for that modality. A file the embedder refuses — a format it does not accept, or on Amazon Nova 2 a recording longer than 30 seconds — is indexed from its extracted text alone. A PDF or Office document is not embedded whole: it is indexed from its text and, when the source indexes them, from the images inside it. See searching with a photo.

A web page's media is fetched through an SSRF guard; an individual asset that fails to download is left out, and one that is unusually large (over 10 MB for an image, 25 MB for video) is listed as not searchable with the reason and is not counted, leaving the rest of the page and the text index intact. An image over 10 MB inside a PDF or Office file is listed the same way. Each attached image or video is billed as an attached file is.

There is no limit on how much media one item contributes. A 200-page catalogue has 200 figures attached, the same way a long text document is split into as many chunks as it takes. Usage scales with what you index, so a media-heavy source costs proportionally more.

A web page's media is attached in the background once the page itself is indexed, so it appears under the item's Attachments, and becomes searchable, after the page's text does.

A web page's remote media is the exception. A page that links out to hundreds of separate image or video files would mean hundreds of downloads from someone else's server, so one pass will only fetch so much — 100 downloads, two minutes of fetching, and 250 MB in total.

A page cut short — one that ran out of that download budget or that could not be read to the end — is marked media capped in the content lists, and opening it shows how many assets were indexed. That marker matters: media search will not match anything past the cut, and without it a partly-indexed page looks identical to a fully-indexed one. To index the rest, re-upload the file or re-fetch the page once it has changed — that produces a new version, which is extracted again from the start. A PDF or Office file is marked this way when it could not be read to the end, such as a damaged file: the images before that point are attached, and the rest are not.

Where a media match came from. Each image is indexed on its own, so a match points at that individual image. An image from a web page or a document is an attachment of its item: the match is reported under the item, with the attachment's name added to the title, as in Assembly Manual (attachment: page_7_image_0.png). Results carry the locators the source format actually provides:

These fields appear in the retrieval step output and in the search_knowledge_base MCP tool result, and a citation names the image by that title, and by its page for a PDF (e.g. [image: Assembly Manual (attachment: page_7_image_0.png) (page 7, match 1)]). Content indexed before this was added keeps its old chunks until the source is re-indexed.

What a media match returns as its text. An extracted image has no text of its own, so the content field of a match carries the image's label — the alt text of an <img>, or the title or aria-label of a <video>. Three things to know about it:

• It is capped at 512 characters, and a longer one is cut with a trailing … rather than dropped. The label comes from the page being indexed, not from you, so it is bounded before it is stored — otherwise a single image could take up more of an agent's prompt than every real match around it. A genuine alt attribute is well under this; accessibility guidance recommends staying below about 125 characters.
• Line breaks in it are flattened to spaces. A label is a caption, not a document, and retrieval results are read by a model — one that could introduce new lines could dress itself up as a second match.
• It is searchable. The label is indexed as the text of the attachment, so a search for its wording finds the image whatever the embedding model does with words sent beside a picture.

An extracted asset with no label at all — or one that is only whitespace or invisible characters — is cited by name instead: content carries the citation itself, [image: Pricing (attachment: chart.png) (match 3)], so a match is never a blank body. That applies to any kind of asset, not just images: a <video> with no title or aria-label is cited the same way. An image attached from a PDF is always cited this way, since a PDF figure has no alt attribute to take. Square brackets inside a label are rewritten to parentheses, so a label can never be mistaken for one of those citations.

Chat

Every knowledge base has a built-in chat interface that lets you have interactive conversations with your indexed content. The chat uses RAG under the hood — each message triggers a retrieval against the knowledge base, then feeds the relevant content to an LLM to generate a grounded response.

Starting a conversation

Open a knowledge base and switch to the Chat tab. Type a question and press Enter. A new conversation is created automatically, and the response streams back in real time.

Key capabilities:

• Ask with a file — Attach an image, audio file, video or PDF to your message and the knowledge base is searched with the file itself, not just your words: photograph a page and ask which document it came from. Requires the knowledge base to be indexed with an embedder that reads that kind of file; a file it cannot read — a PDF, on every embedder — is set aside and your question is searched on its own. A message is still required, so a file always accompanies a question rather than replacing it. See searching with a photo for the full rules, including which embedders read which kinds.
• Multiple conversations — Create as many conversations as you need. Each one maintains its own message history and can be renamed, archived, or deleted.
• Model selection — Choose between Fast (Nova Lite), Balanced (Claude Sonnet), and Thorough (Claude Opus) tiers per message. You can also select a specific model from the full model catalogue.
• Streaming responses — Responses stream token-by-token so you see results immediately.
• Conversation management — Rename conversations for easy reference, archive old ones to keep the sidebar clean, or bulk-delete conversations you no longer need.
• Regenerate responses — If a response isn't satisfactory, regenerate it to get a fresh answer.
• Copy and feedback — Copy any message to your clipboard, and use the thumbs-up/down feedback buttons to rate response quality.

How it works

When you send a message, Seclai:

1. Retrieves relevant content chunks from the knowledge base using the configured retrieval settings (Top N, Top K, reranker, score threshold)
2. Constructs a RAG prompt with the retrieved context and your conversation history
3. Sends the prompt to the selected model and streams the response back

Conversations persist across sessions — come back any time to continue where you left off.

API Access

Knowledge bases can be managed programmatically via the Public API using your API key:

# List knowledge bases
curl "https://api.seclai.com/knowledge_bases?page=1&limit=20" \
  -H "X-API-Key: $SECLAI_API_KEY"

# Create a knowledge base
curl -X POST https://api.seclai.com/knowledge_bases \
  -H "X-API-Key: $SECLAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tech News KB",
    "description": "Aggregated tech news sources",
    "source_ids": ["source-id-1", "source-id-2"]
  }'

# Get a knowledge base
curl "https://api.seclai.com/knowledge_bases/$KNOWLEDGE_BASE_ID" \
  -H "X-API-Key: $SECLAI_API_KEY"

# Update a knowledge base. Only the fields you send are changed;
# the rest are left exactly as they were.
curl -X PUT "https://api.seclai.com/knowledge_bases/$KNOWLEDGE_BASE_ID" \
  -H "X-API-Key: $SECLAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Renamed KB", "default_top_k": 10}'

# Turn reranking off. Send the string "none" — omitting the field, or
# sending null, leaves the current reranker in place.
curl -X PUT "https://api.seclai.com/knowledge_bases/$KNOWLEDGE_BASE_ID" \
  -H "X-API-Key: $SECLAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reranker_model": "none"}'

# Delete a knowledge base
curl -X DELETE "https://api.seclai.com/knowledge_bases/$KNOWLEDGE_BASE_ID" \
  -H "X-API-Key: $SECLAI_API_KEY"

Field names in the request body must match exactly — unrecognised keys are ignored, not rejected, so a misspelled field silently does nothing. The retrieval settings are reranker_model, default_top_n, default_top_k and default_score_threshold.

source_ids replaces the whole list, so send every source you want to keep, not just the new ones. Omit the field to leave the sources untouched. An empty list is rejected — a knowledge base must keep at least one source; to stop using one entirely, delete it.

To see which reranker model ids you can pass, and what each costs:

curl "https://api.seclai.com/models/rerankers" \
  -H "X-API-Key: $SECLAI_API_KEY"

Each entry carries the model_type to pass as reranker_model, its credits_per_action, and whether it is the platform default (is_default — what you get when you omit reranker_model on create).

Turning reranking off is not a model, so it does not appear in that list: pass the literal string "none" as reranker_model.

See API Examples for more examples in multiple languages.

MCP Tools

Knowledge base operations are available as MCP tools for AI coding assistants:

See MCP Server → Knowledge Base Tools for setup instructions.

Exporting

Export a knowledge base's full content — sources, metadata, and indexed items — as a downloadable JSON file.

• UI: Open the knowledge base detail page and click the Export button. You'll see an estimate of the export size before confirming.
• API: POST /authenticated/resource-exports with resource_type: "knowledge_base" and the knowledge base ID.
• MCP: Use the create_resource_export tool with resource_type: "knowledge_base".

See Export Formats → Knowledge Base for the full file schema and available filter options.

Next Steps

• Content Sources — Learn about content sources
• Contents — Inspect, replace, and delete indexed content items
• Agents — Build agents that use knowledge bases
• API Examples — Code samples for the API
• API Reference — Complete API documentation
• MCP Server — Use knowledge base tools from AI coding assistants