Knowledge API

Knowledge-base entries are content you give an agent directly — separate from crawled Sites. Entries can be plain text or an uploaded document; on create they are chunked and embedded so the agent can retrieve them during conversations. Reading is gated on sites.read; writing on knowledge.write.

An entry is scoped to exactly one of widget_id (agent-level) or kb_id (a reusable, org-level knowledge base that can be attached to many agents).

List entries

GET /api/v1/rest/kb-entries   ?widget_id=   |   ?kb_id=

Filter by agent or by knowledge base. Text entries include their content so you can do a read-modify-write.

Create a text entry

POST /api/v1/rest/kb-entries
{
  "kb_id": "uuid",           // or "widget_id"
  "title": "Service hours",
  "text":  "We are open Monday to Friday, 9am to 6pm…"
}

The text is chunked and embedded synchronously — the response returns once the entry is searchable, with char_count and chunk_count populated.

Create a document entry

Upload a pdf / docx / txt / md file in two steps: request a signed upload URL, PUT the bytes to it, then register the file so Seny extracts its text and embeds it.

POST /api/v1/rest/kb-entries/sign-upload
{
  "kb_id": "uuid",           // or "widget_id"
  "file_name": "menu.pdf",
  "file_size": 48213
}
// → { "upload_url": "...", "file_path": "..." }

PUT <upload_url>             // the raw file bytes

POST /api/v1/rest/kb-entries
{
  "kb_id": "uuid",
  "file_path": "<from sign-upload>",
  "file_name": "menu.pdf"
}

Get, update, delete

GET    /api/v1/rest/kb-entries/:id
PATCH  /api/v1/rest/kb-entries/:id      # edit a text entry's title/text (re-embeds)
DELETE /api/v1/rest/kb-entries/:id

Editing a text entry's text re-chunks and re-embeds it. Deleting removes the entry, its embedded chunks, and — for document entries — the stored source file.

Knowledge bases & website sources

Manage reusable knowledge bases at /api/v1/rest/knowledge-bases (list / create / get / update / delete) and attach them to an agent with GET/PUT /api/v1/rest/agents/:id/knowledge-bases. A knowledge base can also crawl websites — add, list, recrawl, or remove a source under /api/v1/rest/knowledge-bases/:id/sources. Full schemas are in the OpenAPI reference.