add workflows section

Author: humford

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

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.
 

fern/docs.yml

@@ -138,6 +138,18 @@ navigation:
           - 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/apiRequest.mdx
+                  - page: Transfer
+                    path: workflows/verbs/transfer.mdx
+                  - page: Hangup
+                    path: workflows/verbs/hangup.mdx
               - page: Tasks
                 path: workflows/tasks.mdx
           - section: Blocks

fern/introduction.mdx

@@ -1,5 +1,5 @@
 ---
-title: Introduction
+title: Introduction to Vapi
 subtitle: Vapi is the Voice AI platform for developers.
 slug: introduction
 ---

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:

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:
 

fern/tools/introduction.mdx

@@ -1,10 +1,10 @@
 ---
-title: Introduction
+title: Introduction to Tools
 subtitle: Extend your assistant's capabilities with powerful function calling tools.
 slug: tools
 ---
 
-**Tools** allow your assistant to take actions beyond just conversation. They enable your assistant to perform tasks like transferring calls, accessing external data, or triggering actions in your application. Tools can be either built-in default tools provided by Vapi or custom tools that you create.
+[**Tools**](/api-reference/tools/create) allow your assistant to take actions beyond just conversation. They enable your assistant to perform tasks like transferring calls, accessing external data, or triggering actions in your application. Tools can be either built-in default tools provided by Vapi or custom tools that you create.
 
 There are three types of tools available:
 
@@ -13,7 +13,7 @@ There are three types of tools available:
 3. **Integration Tools**: Pre-built integrations with platforms like [Make](https://www.make.com/en/integrations/vapi) and GoHighLevel (GHL) that let you trigger automated workflows via voice.
 
 <Info>
-  Tools are configured as part of your assistant's model configuration. You can find the complete API reference [here](/api-reference/assistants/create-assistant).
+  Tools are configured as part of your assistant's model configuration. You can find the complete API reference [here](/api-reference/tools/create-tool).
 </Info>
 
 ## Available Tools

fern/workflows.mdx

@@ -0,0 +1,11 @@
+---
+title: Introduction to Workflows
+subtitle: Breaking down AI conversations into discrete steps
+slug: workflows
+---
+
+<Success intent="launch">
+  Workflows is now available to all Vapi users. Start building more reliable and structured conversational AI today.
+</Success>
+
+Workflows is a new way to build conversational AI. It allows you to break down AI conversations into discrete steps, and then orchestrate those steps in a way that is easy to manage and modify.