Managed knowledge base (RAG)

1. Upsert documents

Chunk your docs to ~500 tokens each, send one upsert call per chunk. Use a stable `id` so re-runs idempotently update.

bash# Upsert one chunk. Re-running with the same id replaces in place.
curl -X POST https://www.upivia.com/v1/service-requests \
  -H "Authorization: Bearer $AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "service":"knowledge",
    "operation":"upsert",
    "payload":{
      "collection":"handbook",
      "documents":[{"id":"hb-001","text":"<chunk>","metadata":{"source":"handbook.md"}}]
    }
  }'

2. Query

Ask in plain English; the platform embeds, searches, and returns top-k chunks with similarity scores.

bash# Top-k retrieval against the handbook collection.
curl -X POST https://www.upivia.com/v1/service-requests \
  -H "Authorization: Bearer $AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "service":"knowledge",
    "operation":"query",
    "payload":{"collection":"handbook","query":"refund policy for annual plans","top_k":5}
  }'

3. Synthesize

Stuff the retrieved chunks into a GPT-4o prompt as `context`. Ask for a cited answer. Use knowledge.list_collections to UI a picker.