From 4bac90fc302c5f96e63ad09ae166829ab4e306aa Mon Sep 17 00:00:00 2001
From: Chiranjeet Mishra <chiranjeet@vapi.ai>
Date: Wed, 14 Oct 2026 03:45:41 +0000
Subject: [PATCH] docs: custom KB uuid must be a UUID v4; direct response is a
 custom-message

The API accepts only a UUID v4 in documents[].uuid and discards a response
that fails validation. The direct response field is a custom message
({ type: 'custom-message', content }), not a role/content chat message.
Example servers no longer map arbitrary IDs or titles into uuid.
---
 .../knowledge-base/implement-custom-endpoint.mdx | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/fern/knowledge-base/implement-custom-endpoint.mdx b/fern/knowledge-base/implement-custom-endpoint.mdx
index 370e9ea3d..19f508e25 100644
--- a/fern/knowledge-base/implement-custom-endpoint.mdx
+++ b/fern/knowledge-base/implement-custom-endpoint.mdx
@@ -52,25 +52,29 @@ Return an array of relevant documents that the AI will use to formulate a respon
     {
       "content": "Our return policy allows customers to return items within 30 days of purchase for a full refund. Items must be in original condition with tags attached.",
       "similarity": 0.92,
-      "uuid": "doc-return-policy-1" // optional
+      "uuid": "3f1c2b9e-8d4a-4f6b-9c2e-7a5d1e0b4c3f" // optional, must be a UUID v4
     },
     {
       "content": "Extended return periods apply during holiday seasons - customers have up to 60 days to return items purchased between November 1st and December 31st.",
       "similarity": 0.78,
-      "uuid": "doc-return-policy-holiday" // optional
+      "uuid": "9b7e4d21-5c3a-4e8f-a1d6-2f0c8b9e7a54" // optional, must be a UUID v4
     }
   ]
 }
 ```
 
+<Warning>
+  Vapi validates the whole response. If `uuid` is present it must be a UUID v4; any other value, such as a document title or a numeric ID, fails validation and Vapi discards the entire response, so the assistant answers without your documents. Omit `uuid` if your IDs are not UUIDs.
+</Warning>
+
 #### Option 2: Return Direct Response
 
-Return a complete response that the assistant will speak directly:
+Return a `custom-message` that the assistant will speak directly instead of generating a response. `content` is limited to 1,000 characters:
 
 ```json title="Direct Response"
 {
   "message": {
-    "role": "assistant",
+    "type": "custom-message",
     "content": "You have 30 days to return items for a full refund. Items must be in original condition with tags attached. During the holiday season (November 1st to December 31st), you get an extended 60-day return period."
   }
 }
@@ -144,7 +148,6 @@ app.post('/kb/search', (req, res) => {
       documents: relevantDocs.map(doc => ({
         content: doc.content,
         similarity: doc.similarity,
-        uuid: doc.id
       }))
     });
 
@@ -239,7 +242,6 @@ async def knowledge_base_search(request: Request):
                 {
                     "content": doc['content'],
                     "similarity": doc['similarity'],
-                    "uuid": doc['id']
                 }
                 for doc in relevant_docs
             ]
@@ -301,7 +303,6 @@ app.post('/kb/search', async (req, res) => {
     const documents = searchResults.matches.map(match => ({
       content: match.metadata.content,
       similarity: match.score,
-      uuid: match.id
     }));
 
     res.json({ documents });
@@ -338,7 +339,6 @@ async def search_with_weaviate(request: Request):
             documents.append({
                 "content": doc['content'],
                 "similarity": doc['_additional']['certainty'],
-                "uuid": doc.get('title', 'unknown')
             })
 
         return {"documents": documents}