Knowledge base

The knowledge base lets an agent ground its answers in your own documents — product manuals, FAQs, internal SOPs, brochures, screenshots — instead of relying only on the system prompt.

You upload sources at the workspace level, attach them to specific agents, and Hyponema runs retrieval-augmented generation (RAG) at conversation time. Only attached sources are visible to a given agent.

Source kinds

Kind	How to upload
File	Upload PDF, Markdown, plain text, HTML, JSON, DOCX, EPUB, PNG / JPEG / WEBP. Hyponema parses, OCRs when needed, chunks, and embeds.
Inline	Paste text directly. Useful for short policies, scripts, or canned responses.

Supported MIME types are checked at upload time; anything else is rejected before the body is buffered. Per-plan storage and per-upload size limits apply — the API returns 402 Payment Required with a quota-exceeded-kb-storage or quota-exceeded-kb-upload-size code when you hit the ceiling.

Upload from the dashboard

Open Knowledge in the dashboard. Drag a file in, or click New inline source for pasted text. Sources show parsing progress and a heartbeat while they’re processed in the background. When status is ready, the source can be attached to agents and queried.

If parsing produced something unexpected, Reprocess re-runs ingestion against the stored blob, optionally forcing OCR on a PDF.

Upload through the API

curl -X POST "https://api.hyponema.ai/workspaces/$WORKSPACE_ID/knowledge-base/sources/upload" \
  -H "Authorization: Bearer $HYPONEMA_API_KEY" \
  -F "file=@./pricing.pdf;type=application/pdf" \
  -F "name=Pricing FAQ"

Inline:

curl -X POST "https://api.hyponema.ai/workspaces/$WORKSPACE_ID/knowledge-base/sources/inline" \
  -H "Authorization: Bearer $HYPONEMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Refund policy v3",
    "content": "Refunds are issued within 14 days of purchase ..."
  }'

Both return 202 Accepted with the source row. Poll GET /workspaces/{ws}/knowledge-base/sources/{source_id} for status.

Attach a source to an agent

A source isn’t visible to an agent until it’s attached. From the agent’s Knowledge tab in the dashboard, or via API:

curl -X POST "https://api.hyponema.ai/workspaces/$WORKSPACE_ID/agents/$AGENT_ID/knowledge-base/attach" \
  -H "Authorization: Bearer $HYPONEMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "source_ids": ["src_...", "src_..."] }'

GET /workspaces/{ws}/agents/{agent_id}/knowledge-base lists attachments. DELETE /workspaces/{ws}/agents/{agent_id}/knowledge-base/{source_id} detaches.

Inspect chunks and try a query

Each source is split into chunks and embedded. List them with GET /workspaces/{ws}/knowledge-base/sources/{source_id}/chunks.

You can simulate a retrieval query against an agent’s full attached corpus:

curl -X POST "https://api.hyponema.ai/workspaces/$WORKSPACE_ID/knowledge-base/query" \
  -H "Authorization: Bearer $HYPONEMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_...",
    "q": "How long do I have to request a refund?",
    "top_k": 5
  }'

The dashboard exposes the same query in the source detail view, ranked by similarity. Tune top_k and min_similarity until you’re happy with what the agent will see at runtime.

What the agent sees at conversation time

When the agent is replying, Hyponema retrieves the most relevant chunks across the agent’s attached sources, scores them by vector similarity, and injects them into the prompt. The model is instructed to ground its answer in those chunks rather than freelance.

Inspect the Retrieval spans in observability for the chunks that actually made it into a turn.

Operational guidance

• Keep sources focused. One large policy document beats fifty near-duplicate files.
• Re-run Reprocess with Force OCR when a scanned PDF parsed empty.
• Delete obsolete sources rather than letting them stay attached and dilute retrieval.
• Watch storage usage on Billing — knowledge base bytes count toward your plan’s storage limit.