Knowledge Sources

Attach text, URL, or file-backed knowledge to an agent so its retrieval pipeline can pull relevant snippets into the prompt at call time. Rymi chunks the text, generates embeddings, and stores them under the agent. The runtime retrieves the top-matching chunks during conversation.

The Studio's Knowledge panel is built on these endpoints — see the Business Profile guide for end-to-end usage.

Quotas

Tenants have soft and hard caps on knowledge sources count and total bytes. The hard cap returns 429 quota_exceeded.knowledge_*. A soft breach proceeds but adds an x-rymi-quota-soft-breach response header.

Create from text or URL

POST /v1/agents/:id/knowledge-sources

Creates a source row in pending and starts ingestion. When a BullMQ worker is wired in this environment, ingestion runs async and the route returns 202 — poll the GET endpoint until status flips to ready or failed. Without a worker (tests / minimal deployments), ingestion runs inline and the route returns 201 with the final state.

Request Body

Field	Type	Required	Description
kind	"text" | "url"	yes	Source kind
title	string	yes	Display name (max 200 bytes)
text	string	conditional	Required when kind="text". Max 1 MB
url	string	conditional	Required when kind="url". Rymi fetches and extracts text

Response 202 / 201

{
  "source": {
    "id": "ks_...",
    "agent_id": "agent_...",
    "kind": "text",
    "title": "Refund policy",
    "source_uri": null,
    "status": "pending",
    "chunk_count": 0,
    "bytes": 4823,
    "created_at": "..."
  }
}

Errors

Status	Code	Meaning
400	—	Missing / invalid kind, title, text, or url
404	—	Agent not found for this tenant
413	—	text exceeds the 1 MB inline cap
429	quota_exceeded.knowledge_sources_max	Source-count hard cap reached
429	quota_exceeded.knowledge_bytes_max	Total bytes hard cap reached

---

Upload a File

POST /v1/agents/:id/knowledge-sources/upload

Multipart upload for txt, md, pdf, docx, html, and json files up to 10 MB. Streams the file to Supabase Storage under {tenant_id}/{source_id}/{filename}, creates the source row in pending, and enqueues extraction + embedding.

Requires the async ingestion worker. Returns 503 when the deployment hasn't wired one.

Form Fields

Field	Type	Required	Description
file	binary	yes	The file to upload
title	string	no	Display name; defaults to the filename

Example Request

curl -X POST https://api.rymi.live/v1/agents/agent_123/knowledge-sources/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "title=Refund policy v2" \
  -F "file=@./refund-policy.pdf"

Response 202

{
  "source": {
    "id": "ks_...",
    "kind": "file",
    "title": "Refund policy v2",
    "source_uri": "refund-policy.pdf",
    "status": "pending",
    "bytes": 482301
  }
}

Errors

Status	Meaning
400	Missing multipart file field, or title exceeds 200 bytes
404	Agent not found
413	File exceeds the 10 MB cap
429	Quota hard cap reached (see codes above)
503	Ingestion worker not configured in this environment

---

List Sources

GET /v1/agents/:id/knowledge-sources

Returns all knowledge sources for the agent ordered by most recent. Chunks are not returned — this is a metadata view used for polling ingestion status and rendering the Studio panel.

Response 200

{
  "sources": [
    {
      "id": "ks_...",
      "kind": "file",
      "title": "Refund policy v2",
      "status": "ready",
      "chunk_count": 12,
      "bytes": 482301,
      "failure_reason": null,
      "created_at": "..."
    }
  ]
}

status	Meaning
pending	Created — ingestion enqueued or in flight
ready	Embeddings stored — available to retrieval
failed	Ingestion failed — see failure_reason

---

Delete a Source

DELETE /v1/agents/:id/knowledge-sources/:sourceId

Removes the source and cascades chunks. Returns 204 on success.