Knowledge (RAG)

Give your agents knowledge by creating collections, ingesting content, and enabling retrieval-augmented generation.

How It Works

1. Create a collection — a named container for documents
2. Ingest content — text, transcripts, or audio are chunked and embedded into vectors
3. Attach to an agent — set the agent's collectionId
4. Automatic retrieval — during conversations, the agent queries the collection for relevant context before responding

The RAG pipeline uses hybrid search: 80% vector similarity (pgvector) + 20% keyword matching (tsvector).

Create a Collection

curl -X POST https://persona-labsvoice-api-production.up.railway.app/v1/collections \
  -H "Authorization: Bearer $PH0NY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Knowledge Base",
    "description": "Product docs, FAQs, and support articles"
  }'

Ingest Content

Text

curl -X POST https://persona-labsvoice-api-production.up.railway.app/v1/collections/:id/ingest \
  -H "Authorization: Bearer $PH0NY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Our premium plan includes unlimited API calls, priority support, and custom voice cloning. Pricing starts at $99/month...",
    "contentType": "text",
    "chunkSize": 1000,
    "chunkOverlap": 200,
    "metadata": {
      "source": "pricing-page",
      "category": "billing"
    }
  }'

Transcript

curl -X POST https://persona-labsvoice-api-production.up.railway.app/v1/collections/:id/ingest \
  -H "Authorization: Bearer $PH0NY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Speaker 1: Welcome to the show...",
    "contentType": "transcript"
  }'

Audio (auto-transcribed)

curl -X POST https://persona-labsvoice-api-production.up.railway.app/v1/collections/:id/ingest \
  -H "Authorization: Bearer $PH0NY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceUrl": "https://example.com/podcast-episode.mp3",
    "contentType": "audio"
  }'

Audio is transcribed via STT before chunking and embedding.

Ingest Options

Field	Type	Default	Description
content	string	-	Raw text content (up to 1MB)
sourceUrl	string	-	URL to fetch content from
contentType	string	"text"	text, transcript, audio, or url
chunkSize	number	1000	Characters per chunk (100-4000)
chunkOverlap	number	200	Overlap between chunks (0-500)
metadata	object	-	Arbitrary metadata attached to chunks

Search

Query a collection directly:

curl -X POST https://persona-labsvoice-api-production.up.railway.app/v1/collections/:id/search \
  -H "Authorization: Bearer $PH0NY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "what is the return policy?",
    "limit": 5,
    "threshold": 0.7,
    "includeMetadata": true
  }'

Response:

{
  "results": [
    {
      "content": "Returns are accepted within 30 days of purchase...",
      "score": 0.89,
      "metadata": { "source": "faq", "category": "returns" }
    }
  ]
}

Attach to an Agent

When creating or updating an agent, set the collectionId:

curl -X PUT https://persona-labsvoice-api-production.up.railway.app/v1/agents/agent_abc123 \
  -H "Authorization: Bearer $PH0NY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "collectionId": "coll_xyz789"
  }'

The agent will now automatically search the collection for relevant context on every conversational turn.

Delete a Document

curl -X DELETE https://persona-labsvoice-api-production.up.railway.app/v1/collections/:collectionId/documents/:documentId \
  -H "Authorization: Bearer $PH0NY_API_KEY"

Delete a Collection

curl -X DELETE https://persona-labsvoice-api-production.up.railway.app/v1/collections/:id \
  -H "Authorization: Bearer $PH0NY_API_KEY"

Deleting a collection removes all documents and chunks. Any agents referencing this collection will lose their knowledge source.