VapiAI · humford · Feb 16, 2025 · Feb 15, 2025 · Feb 15, 2025 · Feb 15, 2025
diff --git a/fern/assistants.mdx b/fern/assistants.mdx
@@ -1,11 +1,12 @@
 ---
-title: Introduction
+title: Introduction to Assistants
 subtitle: The core building-block of voice agents on Vapi.
 slug: assistants
 ---
 
-**Assistant** is a fancy word for an AI configuration that can be used across phone calls and Vapi clients. Your voice assistant can augment your customer support and 
-experience for call centers, business websites, mobile apps, and much more.
+[**Assistant**](/api-reference/assistants/create) is a fancy word for an AI configuration that can be used across phone calls and Vapi clients. Your voice assistant can augment your customer support and experience for call centers, business websites, mobile apps, and much more.
+
+<EndpointResponseSnippet endpoint='POST /assistant' />
 
 ## Core Components
 
@@ -18,7 +19,7 @@ There are three core components that make up an assistant:
 These components can be configured, mixed, and matched for your specific use case.
 
 <Info>
-  View all configurable properties in the [API Reference](/api-reference/assistants/create-assistant)
+  View all configurable properties in the [API Reference](/api-reference/assistants/create-assistant).
 </Info>
 
 ## Key Features

diff --git a/fern/blocks.mdx b/fern/blocks.mdx
@@ -1,12 +1,14 @@
 ---
-title: Introduction
+title: Introduction to Blocks
 subtitle: Breaking down bot conversations into smaller, more manageable prompts
 slug: blocks
 ---
 
+<Warning>
+  **Blocks** is being deprecated in favor of [Workflows](/workflows). We recommend using Workflows for all new development as it provides a more powerful and flexible way to structure conversational AI. We're working on migration tools to help transition existing Blocks implementations to Workflows.
+</Warning>
 
-
-We're currently running a beta for **Blocks**, an upcoming feature from [Vapi.ai](http://vapi.ai/) aimed at improving bot conversations. The problem we've noticed is that single LLM prompts are prone to hallucinations, unreliable tool calls, and can’t handle many-step complex instructions.
+We're currently running a beta for [**Blocks**](/api-reference/blocks/create), an upcoming feature from [Vapi.ai](http://vapi.ai/) aimed at improving bot conversations. The problem we've noticed is that single LLM prompts are prone to hallucinations, unreliable tool calls, and can’t handle many-step complex instructions.
 
 **By breaking the conversation into smaller, more manageable prompts**, we can guarantee the bot will do this, then that, or if this happens, then that happens. It’s like having a checklist for conversations — less room for error, more room for getting things right.
 

diff --git a/fern/blocks/block-types.mdx b/fern/blocks/block-types.mdx
@@ -4,6 +4,9 @@ subtitle: 'Building the Logic and Actions for Each Step in Your Conversation '
 slug: blocks/block-types
 ---
 
+<Warning>
+  **Blocks** is being deprecated in favor of [Workflows](/workflows). We recommend using Workflows for all new development as it provides a more powerful and flexible way to structure conversational AI. We're working on migration tools to help transition existing Blocks implementations to Workflows.
+</Warning>
 
 [**Blocks**](https://api.vapi.ai/api#/Blocks/BlockController_create) are the functional units within a Step, defining what action happens at each stage of a conversation. Each Step can contain only one Block, and there are three main types of Blocks, each designed to handle different aspects of conversation flow.
 

diff --git a/fern/blocks/steps.mdx b/fern/blocks/steps.mdx
@@ -4,13 +4,12 @@ subtitle: Building and Controlling Conversation Flow for Your Assistants
 slug: blocks/steps
 ---
 
+<Warning>
+  **Blocks** is being deprecated in favor of [Workflows](/workflows). We recommend using Workflows for all new development as it provides a more powerful and flexible way to structure conversational AI. We're working on migration tools to help transition existing Blocks implementations to Workflows.
+</Warning>
 
 [**Steps**](https://api.vapi.ai/api#:~:text=HandoffStep) are the core building blocks that dictate how conversations progress in a bot interaction. Each Step represents a distinct point in the conversation where the bot performs an action, gathers information, or decides where to go next. Think of Steps as checkpoints in a conversation that guide the flow, manage user inputs, and determine outcomes. 
 
-<Note>
-  Blocks is currently in beta. We're excited to have you try this new feature and welcome your [feedback](https://discord.com/invite/pUFNcf2WmH) as we continue to refine and improve the experience.
-</Note>
-
 #### Features
 
 - **Output:** The data or response expected from the step, as outlined in the block's `outputSchema`.

diff --git a/fern/docs.yml b/fern/docs.yml
@@ -91,15 +91,8 @@ navigation:
     layout:
       - section: Getting Started
         contents:
-          - page: Introduction
-            path: introduction.mdx
-          - section: How Vapi Works
-            contents:
-              - page: Core Models
-                path: quickstart.mdx
-              - page: Orchestration Models
-                path: how-vapi-works.mdx
           - section: Quickstart
+            path: introduction.mdx
             contents:
               - page: Dashboard Quickstart
                 path: quickstart/dashboard.mdx
@@ -109,6 +102,12 @@ navigation:
                 path: quickstart/outbound.mdx
               - page: Web Call Quickstart
                 path: quickstart/web.mdx
+          - section: How Vapi Works
+            contents:
+              - page: Core Models
+                path: quickstart.mdx
+              - page: Orchestration Models
+                path: how-vapi-works.mdx
           - section: Use Cases
             contents:
               - page: Outbound Sales
@@ -122,9 +121,8 @@ navigation:
       - section: Build
         contents:
           - section: Assistants
+            path: assistants.mdx
             contents:
-              - page: Introduction
-                path: assistants.mdx
               - page: Voice AI Prompting Guide
                 path: prompting-guide.mdx
               - page: Persistent Assistants
@@ -137,48 +135,67 @@ navigation:
                 path: assistants/background-messages.mdx
               - page: Voice Formatting Plan
                 path: assistants/voice-formatting-plan.mdx
+          - section: Workflows
+            path: workflows.mdx
+            contents:
+              - section: Verbs
+                contents:
+                  - page: Say
+                    path: workflows/verbs/say.mdx
+                  - page: Gather
+                    path: workflows/verbs/gather.mdx
+                  - page: API Request
+                    path: workflows/verbs/api-request.mdx
+                  - page: Transfer
+                    path: workflows/verbs/transfer.mdx
+                  - page: Hangup
+                    path: workflows/verbs/hangup.mdx
+              - section: Conditions
+                contents:
+                  - page: Logical Conditions
+                    path: workflows/logical-conditions.mdx
+                  - page: AI Conditions
+                    path: workflows/ai-conditions.mdx
           - section: Blocks
+            path: blocks.mdx
             contents:
-              - page: Introduction
-                path: blocks.mdx
               - page: Steps
                 path: blocks/steps.mdx
               - page: Block Types
                 path: blocks/block-types.mdx
           - section: Tools
+            path: tools/introduction.mdx
             contents:
-              - page: Introduction
-                path: tools/introduction.mdx
               - page: Default Tools
                 path: tools/default-tools.mdx
               - page: Custom Tools
                 path: tools/custom-tools.mdx
               - page: Make & GHL Tools
                 path: GHL.mdx
           - section: Knowledge Base
+            path: knowledge-base/knowledge-base.mdx
             contents:
-              - page: Introduction
-                path: knowledge-base/knowledge-base.mdx
               - page: Integrating with Trieve
                 path: knowledge-base/integrating-with-trieve.mdx
           - section: Squads
+            path: squads.mdx
             contents:
-              - page: Introduction
-                path: squads.mdx
               - page: Example
                 path: squads-example.mdx
               - page: Silent Transfers
                 path: squads/silent-transfers.mdx
-      # - section: Test
-      #   contents:
-      #     - page: Voice Testing
-      #       path: support.mdx
+      - section: Test
+        contents:
+          - page: Manual Testing
+            hidden: true
+            path: test/manual-testing.mdx
+          - page: Voice AI Testing
+            path: test/voice-testing.mdx
       - section: Deploy
         contents:
           - section: Calls
+            path: phone-calling.mdx
             contents:
-              - page: Introduction
-                path: phone-calling.mdx
               - page: Call Forwarding
                 path: call-forwarding.mdx
               - page: Dynamic Call Transfers
@@ -192,9 +209,8 @@ navigation:
               - page: Voice Mail Detection
                 path: calls/voice-mail-detection.mdx
           - section: Vapi SDKs
+            path: sdks.mdx  
             contents:
-              - page: Overview
-                path: sdks.mdx
               - section: Client SDKs
                 contents:
                   - page: Web SDK
@@ -206,19 +222,17 @@ navigation:
               - page: Code Resources
                 path: resources.mdx
           - section: Server URLs
+            path: server-url.mdx
             contents:
-              - page: Introduction
-                path: server-url.mdx
               - page: Setting Server URLs
                 path: server-url/setting-server-urls.mdx
               - page: Server Events
                 path: server-url/events.mdx
               - page: Developing Locally
                 path: server-url/developing-locally.mdx
           - section: SIP Telephony
+            path: advanced/sip/sip.mdx
             contents:
-              - page: SIP Introduction
-                path: advanced/sip/sip.mdx
               - page: Telnyx Integration
                 path: advanced/sip/sip-telnyx.mdx
       - section: Advanced Concepts

diff --git a/fern/introduction.mdx b/fern/introduction.mdx
@@ -1,5 +1,5 @@
 ---
-title: Introduction
+title: Introduction to Vapi
 subtitle: Vapi is the Voice AI platform for developers.
 slug: introduction
 ---

diff --git a/fern/knowledge-base/knowledge-base.mdx b/fern/knowledge-base/knowledge-base.mdx
@@ -1,5 +1,5 @@
 ---
-title: Creating Custom Knowledge Bases for Your Voice AI Assistants
+title: Introduction to Knowledge Bases
 subtitle: >-
   Learn how to create and integrate custom knowledge bases into your voice AI
   assistants.
@@ -8,7 +8,7 @@ slug: knowledge-base
 
 ## **What is Vapi's Knowledge Base?**
 
-A Knowledge Base is a collection of custom files that contain information on specific topics or domains. By integrating a Knowledge Base into your voice AI assistant, you can enable it to provide more accurate and informative responses to user queries. This is currently available in Vapi via the API, and will be on the dashboard soon.
+A [**Knowledge Base**](/api-reference/knowledge-bases/create) is a collection of custom files that contain information on specific topics or domains. By integrating a Knowledge Base into your voice AI assistant, you can enable it to provide more accurate and informative responses to user queries. This is currently available in Vapi via the API, and will be on the dashboard soon.
 
 ### **Why Use a Knowledge Base?**
 
@@ -18,6 +18,10 @@ Using a Knowledge Base with your voice AI assistant offers several benefits:
 - **Enhanced capabilities**: A Knowledge Base enables your assistant to answer complex queries and provide detailed responses to user inquiries.
 - **Customization**: With a Knowledge Base, you can tailor your assistant's responses to specific domains or topics, making it more effective and informative.
 
+<Info>
+  Knowledge Bases are configured through the API, view all configurable properties in the [API Reference](/api-reference/knowledge-bases/create-knowledge-base).
+</Info>
+
 ## **How to Create a Knowledge Base**
 
 To create a Knowledge Base, follow these steps:

diff --git a/fern/prompting-guide.mdx b/fern/prompting-guide.mdx
@@ -44,7 +44,7 @@ To enhance clarity and maintainability, it's recommended to break down system pr
 
 **Example:**
 
-```
+```md wordWrap
 [Identity]
 You are a helpful and knowledgeable virtual assistant for a travel booking platform.
 
@@ -69,7 +69,7 @@ You are a helpful and knowledgeable virtual assistant for a travel booking platf
 For complex interactions, breaking down the task into a sequence of steps enhances the agent's understanding and ensures a structured conversation flow. Incorporate conditional logic to guide the agent's responses based on user input.
 Example:
 
-```
+```md wordWrap
 [Task]
 1. Welcome the user to the technical support service.
 2. Inquire about the nature of the technical issue.
@@ -82,7 +82,7 @@ Example:
 
 To prevent the agent from rushing through the conversation, explicitly indicate when to wait for the user's response before proceeding to the next step.
 
-```
+```md wordWrap
 [Task]
 1. Inform the user about the purpose of the call.
 2. Ask for the user's name and account information.
@@ -95,7 +95,7 @@ To prevent the agent from rushing through the conversation, explicitly indicate
 Specify when and how the agent should utilize external tools or APIs. Reference the tools by their designated names and describe their functions to ensure accurate invocation.
 Example:
 
-```
+```md wordWrap
 [Task]
 ...
 3. If the user wants to know about something, use the get_data function with the parameter 'query', which will contain the user's question to initiate the process.
@@ -108,7 +108,7 @@ If the AI determines that the user needs to be transferred, do not send any text
 
 Always include fallback options and error-handling mechanisms in your prompts. This ensures that the Agent can gracefully handle unexpected user inputs or system errors.
 
-```
+```md wordWrap
 [Error Handling]
 If the customer's response is unclear, ask clarifying questions. If you encounter any issues, inform the customer politely and ask to repeat.
 ```
@@ -134,7 +134,7 @@ When working with numbers that need to be expressed in writing, it's often prefe
 
 Add personality and provide tone to the assistant to make it sound more like a human being. Here are some examples:
 
-```
+```md wordWrap
 - Tone: conversational, spartan, use less corporate jargon
 - Act as Iva, a sales agent who is a human being and has real feelings.
 ```
@@ -143,7 +143,7 @@ Add personality and provide tone to the assistant to make it sound more like a h
 
 ### Appointment Setter
 
-```
+```md wordWrap
 [Role]
 You're Susan, an AI assistant for xxx. Your primary task is to interact with the customer, ask questions, and gather information for appointment booking.
 

diff --git a/fern/squads.mdx b/fern/squads.mdx
@@ -1,17 +1,20 @@
 ---
-title: Squads
+title: Introduction to Squads (Multi-Assistant Conversations)
 subtitle: Use Squads to handle complex workflows and tasks.
 slug: squads
 ---
 
-
 Sometimes, complex workflows are easier to manage with multiple assistants.
 You can think of each assistant in a Squad as a leg of a conversation tree.
 For example, you might have one assistant for lead qualification, which transfers to another for booking an appointment if they’re qualified.
 
 Prior to Squads you would put all functionality in one assistant, but Squads were added to break up the complexity of larger prompts into smaller specialized assistants with specific tools and fewer goals.
 Squads enable calls to transfer assistants mid-conversation, while maintaining full conversation context.
 
+<Info>
+  View all configurable properties in the [API Reference](/api-reference/squads/create-squad).
+</Info>
+
 ## Usage
 
 To use Squads, you can create a `squad` when starting a call and specify `members` as a list of assistants and destinations.
@@ -45,7 +48,7 @@ Transfers are specified by assistant name and are used when the model recognizes
 ```
 
 
-## Best practices
+## Best Practices
 
 The following are some best practices for using Squads to reduce errors:
 

diff --git a/fern/static/images/.DS_Store b/fern/static/images/.DS_Store
diff --git a/fern/static/images/tests/voice-testing-page.png b/fern/static/images/tests/voice-testing-page.png
diff --git a/fern/static/images/workflows/workflow-builder-example.png b/fern/static/images/workflows/workflow-builder-example.png
diff --git a/fern/support.mdx b/fern/support.mdx
@@ -48,7 +48,7 @@ We welcome feature requests and feedback from our users to help improve Vapi. Yo
   <Card 
     title="Submit Bug Report" 
     icon="bug"
-    href="https://roadmap.vapi.ai/bug-reports"
+    href="https://roadmap.vapi.ai/feature-requests"
   >
     Report any bugs or issues you encounter while using Vapi to help us improve the platform.
   </Card>

diff --git a/fern/test/manual-testing.mdx b/fern/test/manual-testing.mdx