Knowledge Base

The Knowledge Base stores structured information that is automatically injected into the LLM system prompt when a voice session starts. Knowledge is managed at the workspace level and shared across all agents in that workspace.

Method 1 — Workspace Memory (Persistent)

Add knowledge items to a workspace. All agents in the workspace automatically inherit this knowledge.

BASH

curl -X POST https://ultravoice.us.inc/api/v1/auth/workspaces/{workspace_id}/memory \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "TechCo Pro plan costs $49/mo. Enterprise plan costs $199/mo. Free trial: 14 days, no credit card required.",
    "title": "Pricing Info",
    "content_type": "knowledge",
    "priority": 1
  }'

Memory Parameters

"content" (string, required) — The knowledge text to inject
"title" (string, optional) — Human-readable label
"content_type" (string, optional) — "knowledge", "instruction", "faq", "context"
"priority" (int, optional) — Injection order, lower = higher priority

Method 2 — Runtime KB (Live Updates)

Add or update knowledge while the system is live without any downtime or agent restart:

BASH

# Add new knowledge at runtime
curl -X POST https://ultravoice.us.inc/api/v1/auth/workspaces/{workspace_id}/memory \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "New product launched: TechCo Teams at $99/mo for up to 25 users.", "title": "Teams Plan"}'

# Update existing memory
curl -X PUT https://ultravoice.us.inc/api/v1/auth/workspaces/{workspace_id}/memory/{memory_id} \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "Updated pricing: Pro is now $39/mo."}'

💡

Runtime updates take effect on the NEXT session start. Active sessions use the knowledge that was loaded at session creation.

Method 3 — Per-Session Context (Dynamic)

Inject custom context per session at start time. Ideal for user-specific data like account details, history, or preferences:

BASH

curl -X POST https://ultravoice.us.inc/api/v1/voice/sessions/start \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "AGENT_ID",
    "user_id": "user-456",
    "dynamic_variables": {
      "customer_name": "Sarah Johnson",
      "account_tier": "Enterprise",
      "open_tickets": "3",
      "last_purchase": "2026-01-15"
    }
  }'

In your system prompt, reference variables with {{variable_name}}: "The customer's name is {{customer_name}} and they are on the {{account_tier}} plan."

Method 4 — Agent-Specific Knowledge

Attach knowledge items directly to an agent for agent-specific context that overrides workspace knowledge:

BASH

curl -X POST https://ultravoice.us.inc/api/v1/agents/{agent_id}/knowledge \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "This sales agent specializes in Enterprise contracts only. Do not discuss SMB pricing.",
    "title": "Agent Scope",
    "priority": 0
  }'

List & Delete Knowledge

BASH

# List all workspace memory
curl https://ultravoice.us.inc/api/v1/auth/workspaces/{workspace_id}/memory \
  -H "Authorization: Bearer $TOKEN"

# Delete a memory item
curl -X DELETE https://ultravoice.us.inc/api/v1/auth/workspaces/{workspace_id}/memory/{memory_id} \
  -H "Authorization: Bearer $TOKEN"