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 runs on these endpoints. See the Business Profile guide for end-to-end usage.

Quotas

Knowledge source count and total bytes are capped per tier in tier_quotas (null means unlimited). When a tier sets a cap, a hard breach returns 429 quota_exceeded.knowledge_* and a soft breach proceeds but adds an x-rymi-quota-soft-breach response header. The current live tiers (free and enterprise) have these source/byte caps lifted to unlimited, so 429 quota_exceeded.knowledge_* does not fire in practice today — the codes below stay documented for tiers that set a cap.

Create from text or URL

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

Creates a source row in pending and starts ingestion. When async ingestion is enabled in this environment, ingestion runs in the background and the route returns 202. Poll the GET endpoint until status flips to ready or failed. Otherwise (tests and 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 (only on tiers that set a cap; current tiers are unlimited)
429	quota_exceeded.knowledge_bytes_max	Total bytes hard cap reached (only on tiers that set a cap; current tiers are unlimited)

---

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. Stores the file securely, 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 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 and 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.