Merge branch 'main' into docs/assemblyai-universal-3-6-pro

Author: stephenvapiai

fern/changelog/2026-09-28.mdx

@@ -0,0 +1,9 @@
+# What's New: Week of September 28, 2026
+
+1. **Composer Per-Conversation Approval Modes**: [Composer](/composer) now lets you choose when each conversation pauses for approval: ask before all changes, allow creates but ask before updates, deletes, runs, or publishing, bypass approvals entirely, or set custom permissions by resource and action.
+
+2. **Eval Run History**: You can now browse your complete [Eval run history](/observability/evals-quickstart#view-run-history) with search and pagination, and share a specific run result by URL.
+
+3. **Fixes and Improvements**:
+    - **Call logs**: The logs table now shows clearer, deterministic error messages for 4xx responses instead of retrying unnecessarily, and the date picker now lets you select the full retention window.
+    - **Voice fallback**: xAI terminal voice failures raised before a call starts are now delivered, the fallback voice no longer greets out of turn, and replacing a voice no longer consumes a second fallback.

fern/composer.mdx

@@ -173,49 +173,42 @@ Composer understands voice agent architecture and Vapi's capabilities. It can cr
 
 ## Safety features
 
-Composer includes safeguards to prevent accidental or irreversible changes to your account.
+Composer includes safeguards to prevent accidental or irreversible changes to your account. You control how much Composer can do on its own with per-conversation approval modes.
 
-### No deletion capability
+### Approval modes
 
-Composer **cannot delete any resources** — assistants, tools, phone numbers, squads, files, or anything else. This is a deliberate safety measure, not a limitation.
+You choose when Composer pauses for your approval, and the setting persists for that conversation:
 
-If you ask Composer to delete something, it directs you to do it yourself:
+- **Ask before every change**: Composer requests approval for all creates, updates, deletes, runs, and publishes.
+- **Ask before updates, deletes, runs, and publishing**: Composer creates new resources on its own, but asks before changing, deleting, running, or publishing anything that already exists.
+- **Bypass approvals**: Composer applies changes without pausing.
+- **Custom**: set permissions for each resource and action individually.
 
-```txt title="Deletion request example"
-You: "Delete my old test assistant"
+Approval enforcement always happens on the server, and read operations never require approval.
 
-Composer: "I'm not able to delete resources to prevent accidental data loss.
-You can delete it yourself from the dashboard — use the sidebar on the left,
-go to Assistants, select the one you want to remove, and delete it from there."
-```
-
-<Note>
-Unlike creating or updating a resource (which can be undone or re-done), deletion is permanent. Requiring manual confirmation through the dashboard UI prevents accidental loss of important configurations.
-</Note>
-
-### Approval required for updates
+### Deletion
 
-When Composer modifies an existing resource (like updating an assistant's prompt, changing a voice setting, or editing a tool configuration), it pauses and asks for your explicit approval first.
+Composer can delete resources such as assistants, tools, phone numbers, squads, and files. Deletion follows your approval mode: unless you have selected Bypass, Composer asks for your explicit approval before it deletes anything. Because deletion is permanent, keep an approval mode on if you want a confirmation step before a resource is removed.
 
-**How the approval flow works:**
+### How the approval flow works
 
 <Steps>
   <Step title="Composer proposes a change">
-    Composer shows you a summary of the update it wants to make.
+    Composer shows you a summary of the change it wants to make.
   </Step>
   <Step title="You review and respond">
     The chat interface displays **Approve** and **Deny** buttons. Click **Approve** to proceed or **Deny** to cancel.
   </Step>
   <Step title="Composer applies the change (if approved)">
-    If approved, Composer makes the update and confirms. If denied, no changes are made.
+    If approved, Composer makes the change and confirms. If denied, no changes are made.
   </Step>
 </Steps>
 
 ```txt title="Approval flow example"
 You: "Change my agent's voice to sound more energetic"
 
 Composer: [Proposes update]
-→ UI shows: "Update Resource — Updating voice settings on assistant xyz"
+UI shows: "Update Resource, updating voice settings on assistant xyz"
   [Approve] [Deny]
 
 You: [Clicks Approve]
@@ -226,10 +219,9 @@ know if you'd like to adjust further."
 
 **Key details about approvals:**
 
-- **Tokens expire after 10 minutes** — if you don't respond in time, Composer needs to re-propose the change
-- **Each approval is specific** — approval tokens are cryptographically bound to the exact change being made; multiple updates each require individual approval
-- **Read operations don't require approval** — Composer can freely read and list your resources without permission
-- **Creating new resources doesn't require approval** — new assistants, tools, and other resources are additive and non-destructive
+- **Tokens expire after 10 minutes**: if you don't respond in time, Composer re-proposes the change.
+- **Each approval is specific**: approval tokens are cryptographically bound to the exact change being made, so multiple changes each require individual approval.
+- **Read operations don't require approval**: Composer can freely read and list your resources.
 
 ## Tips for best results
 

fern/observability/evals-quickstart.mdx

@@ -1136,7 +1136,12 @@ For API details, see [Delete Eval](/api-reference/eval/delete).
        - Target (assistant/squad)
        - Status (pass/fail)
        - Duration
-    4. Click any run to view detailed results
+    4. Search and paginate through your complete run history to find older runs
+    5. Click any run to view detailed results
+
+    <Tip>
+    To share a result, open a run and copy its URL. Anyone with access to your organization can open the link to view that same result, including older runs outside the current page.
+    </Tip>
   </Tab>
 
   <Tab title="cURL">

fern/observability/logs/call-logs.mdx

@@ -97,6 +97,19 @@ This tab shows the stored conversation-message objects for the call, in order. A
 
 Use this tab to inspect the message data retained for the call. The objects are not necessarily the exact payloads sent to or returned by the model provider. The stored history depends on your artifact configuration.
 
+### Function and API Request tools
+
+Use **Messages** to inspect a tool call and its result. Use the call's **Logs** tab to inspect request and response details when the assistant's **Logging** setting is enabled.
+
+| Tool type | Where to inspect | Correlation details |
+| --- | --- | --- |
+| Function | Open **Logs → Webhooks** and find the `tool-calls` entry. Use the call's **Messages** tab to inspect the tool call and result. | The webhook includes the call and tool-call IDs. Vapi also sends the call ID in the `X-Call-Id` header. |
+| API Request | Open the call's **Logs** tab for the resolved request and response. Use **Messages** to inspect the tool call and result. | Vapi sends the call ID in the `X-Call-Id` header. Your destination can return its own `requestId` for its server logs. Vapi does not add `toolCallId` to the destination request by default. |
+
+The **Logs → API** tab records requests made to the Vapi API. It does not show requests that an API Request tool sends to your destination.
+
+For an async Function tool, Vapi returns an immediate `Success.` result to the assistant and ignores the webhook's later result. Open **Logs → Webhooks** to inspect the webhook response after it finishes. Detailed entries in the call's **Logs** tab depend on the assistant's **Logging** setting. See [Logs overview](/observability/logs/overview#retention-and-logging-configuration) for retention and compliance limits.
+
 ### Call Cost
 
 When available, the **Call Cost** tab shows the call's total cost, duration, and per-category breakdown. The tab may be hidden for organizations with invoiced billing. Contact your account team for cost details that reflect your agreement.

fern/openai-realtime.mdx

@@ -17,13 +17,13 @@ OpenAI’s Realtime API enables developers to use a native speech-to-speech mode
 
 ## Available models
 
-OpenAI offers three realtime models, each with different capabilities and cost/performance trade-offs:
+The model picker offers three OpenAI realtime options:
 
-| Model | Status | Best For | Key Features |
-|-------|---------|----------|--------------|
-| `gpt-realtime-2025-08-28` | **Production** | Production workloads | Production Ready |
-| `gpt-4o-realtime-preview-2024-12-17` | Preview | Development & testing | Balanced performance/cost |
-| `gpt-4o-mini-realtime-preview-2024-12-17` | Preview | Cost-sensitive apps | Lower latency, reduced cost |
+| Dashboard option | Model ID | Guidance |
+|------------------|----------|----------|
+| GPT Realtime Cluster | `gpt-realtime-2025-08-28` | Existing assistants |
+| GPT Realtime Mini | `gpt-realtime-mini-2025-12-15` | Cost-sensitive assistants |
+| GPT Realtime 2 | `gpt-realtime-2` | Recommended for new assistants |
 
 ## Voice options
 
@@ -66,7 +66,7 @@ The tool's `body` schema defines the `location` argument the model supplies. For
 {
   "model": {
     "provider": "openai",
-    "model": "gpt-realtime-2025-08-28",
+    "model": "gpt-realtime-2",
     "messages": [
       {
         "role": "system",
@@ -112,7 +112,7 @@ const vapi = new VapiClient({ token: apiKey });
 const assistant = await vapi.assistants.create({
   model: {
     provider: "openai",
-    model: "gpt-realtime-2025-08-28",
+    model: "gpt-realtime-2",
     messages: [{
       role: "system",
       content: "You are a concise, friendly weather assistant. If the caller has not provided a location, ask for one. If the city is ambiguous, ask for the missing region or country before using getWeather. Call getWeather for each new current-weather request, including a request for another city. Pass the complete location, preserving any region/state and country the caller supplied. Use only the latest successful result for the requested location and report the returned location with the weather. If the returned city, region, or country conflicts with the request, clarify before reporting weather. Differences in spelling or formatting alone are not a location mismatch. If the lookup fails or current-weather data is missing, explain that current weather is unavailable. Do not invent weather or reuse an earlier result after a failed lookup."
@@ -154,7 +154,7 @@ vapi = Vapi(token=os.getenv("VAPI_API_KEY"))
 assistant = vapi.assistants.create(
     model={
         "provider": "openai",
-        "model": "gpt-realtime-2025-08-28",
+        "model": "gpt-realtime-2",
         "messages": [{
             "role": "system",
             "content": "You are a concise, friendly weather assistant. If the caller has not provided a location, ask for one. If the city is ambiguous, ask for the missing region or country before using getWeather. Call getWeather for each new current-weather request, including a request for another city. Pass the complete location, preserving any region/state and country the caller supplied. Use only the latest successful result for the requested location and report the returned location with the weather. If the returned city, region, or country conflicts with the request, clarify before reporting weather. Differences in spelling or formatting alone are not a location mismatch. If the lookup fails or current-weather data is missing, explain that current weather is unavailable. Do not invent weather or reuse an earlier result after a failed lookup."
@@ -311,7 +311,7 @@ Transitioning from standard STT/TTS to realtime models:
     {
       "model": {
         "provider": "openai",
-        "model": "gpt-realtime-2025-08-28"  // Changed from gpt-4
+        "model": "gpt-realtime-2"
       }
     }
     ```
@@ -336,32 +336,6 @@ Transitioning from standard STT/TTS to realtime models:
 
 ## Best practices
 
-### Model selection strategy
-
-<AccordionGroup>
-  <Accordion title="When to use gpt-realtime-2025-08-28">
-    **Best for production workloads requiring:**
-    - Structured outputs for form filling or data collection
-    - Complex function orchestration
-    - Highest quality voice interactions
-    - Responses API integration
-  </Accordion>
-  
-  <Accordion title="When to use gpt-4o-realtime-preview">
-    **Best for development and testing:**
-    - Prototyping voice applications
-    - Balanced cost/performance during development
-    - Testing conversation flows before production
-  </Accordion>
-  
-  <Accordion title="When to use gpt-4o-mini-realtime-preview">
-    **Best for cost-sensitive applications:**
-    - High-volume voice interactions
-    - Simple Q&A or routing scenarios
-    - Applications where latency is critical
-  </Accordion>
-</AccordionGroup>
-
 ### Performance optimization
 
 - **Temperature settings**: Use 0.5-0.7 for consistent yet natural responses

fern/providers/model/openai.mdx

@@ -48,6 +48,8 @@ For additional API configuration options, review the [`OpenAIModel` fields](/api
 | GPT 4.1 | `gpt-4.1` |
 | GPT 4.1 Mini | `gpt-4.1-mini` |
 | GPT 4o Mini | `gpt-4o-mini` |
+| GPT Realtime Cluster | `gpt-realtime-2025-08-28` |
+| GPT Realtime Mini | `gpt-realtime-mini-2025-12-15` |
 | GPT Realtime 2 | `gpt-realtime-2` |
 | o3 | `o3` |
 

fern/tools/api-request/response-handling.mdx

@@ -150,12 +150,13 @@ After a test call, inspect the tool arguments and result before changing the sch
 
 <Tabs>
   <Tab title="Dashboard">
-    Open [Logs](https://dashboard.vapi.ai/logs), select the call, and inspect its messages and tool-call entries. Confirm:
+    Open [Logs → Calls](https://dashboard.vapi.ai/logs), select the call, and inspect its **Messages** and **Logs** tabs. Confirm:
 
     - The assistant called the expected tool.
     - The model-generated arguments contain the confirmed customer name, product ID, and quantity.
     - The tool result contains either the accepted order or the structured error.
     - The assistant did not claim success after a failed request.
+    - The **Logs** tab shows the API Request destination's resolved request and response when detailed logging is available.
   </Tab>
 
   <Tab title="cURL">
@@ -174,7 +175,7 @@ After a test call, inspect the tool arguments and result before changing the sch
   </Tab>
 </Tabs>
 
-The call artifact does not show the final HTTP request after Vapi resolves Liquid values and merges static fields. Use logs from the destination API to inspect final headers and body values. Correlate the coffee endpoint's `requestId` with its `X-Request-Id` response header and server logs when investigating a specific request.
+When the assistant's **Logging** setting is enabled, the call's **Logs** tab records the resolved API Request URL, method, request data, and response details. Vapi sends the call ID in the `X-Call-Id` request header. The destination does not receive `toolCallId` by default, so use the call ID and a destination-generated `requestId` to correlate with your server logs. Sensitive values can be redacted or omitted based on logging and compliance settings. The **Logs → API** tab records requests made to Vapi's API, not requests sent by an API Request tool. For Function and API Request tool log locations, see [Call logs](/observability/logs/call-logs#function-and-api-request-tools).
 
 ## Diagnose common failures
 

fern/tools/custom-tools-troubleshooting.mdx

@@ -325,6 +325,8 @@ Tool behavior doesn't match your expectations.
   processing for long-running operations.
 </Tip>
 
+For an async Function tool, Vapi returns an immediate `Success.` result to the assistant and does not use the webhook's eventual response as the tool result. Inspect the later webhook response in [Logs → Webhooks](/observability/logs/webhook-logs) and check your server logs for the completed action. See [Call logs](/observability/logs/call-logs#function-and-api-request-tools) for the Function and API Request log locations.
+
 ## Reference: Required formats
 
 ### Response format template

fern/tools/custom-tools.mdx

@@ -312,6 +312,8 @@ If the location can't be found, report the failure through `error` instead of `r
 
 For multiple tool calls in one request, return a result for every call in the `results` array and match each result to its call with `toolCallId`. Results can appear in any order. Use `result` for success and `error` for failure.
 
+To inspect a Function tool call, open its [call log](/observability/logs/call-logs#function-and-api-request-tools). The call's **Messages** tab shows the tool call and result. **Logs → Webhooks** shows the Function webhook request and response.
+
 **Some Key Points:**
 
 - Pay attention to the required parameters and response format of your functions.