docs: improve Getting Started page and SDK documentation structure (#17614)

Chesars · web-flow · commit dcf5217d1764 · 2025-12-08T13:05:50.000-08:00
* docs: update Getting Started page with accurate endpoints and fix exception handling

- Update endpoints list to include /responses, /audio, /batches
- Change "Consistent output" to be endpoint-agnostic
- Clarify Response Format title as "OpenAI Chat Completions Format"
- Fix exception handling example: use litellm exceptions instead of deprecated openai.error
- Add model prefix (anthropic/) to example

* docs: reorganize sidebar and improve SDK documentation structure

Sidebar changes:
- Reorder: Python SDK first, then AI Gateway (Proxy)
- Rename "LiteLLM - Getting Started" to "Getting Started"
- Restructure SDK section with Core Functions, Configuration subsections
- Move budget_manager to Guides
- Move sdk_custom_pricing and migration to Extras
- Remove duplicate embedding/async_embedding and embedding/moderation

Content changes:
- Add Response Format section to response_api.md
- Add async aembedding() section to supported_embedding.md

* docs: add deprecation notice for OpenAI Assistants API

OpenAI has deprecated the Assistants API, shutting down on August 26, 2026.
Added warning banner directing users to the Responses API.

* docs: expand Core Functions in SDK sidebar

Add more SDK functions to Core Functions category:
- text_completion()
- image_generation()
- transcription()
- speech()
- Link to "All Supported Endpoints" for complete list

* Rename Sidebar Item

* docs: revert Getting Started label to original

* Rename sidebar label from 'LiteLLM - Getting Started' to 'Getting Started'
diff --git a/docs/my-website/docs/assistants.md b/docs/my-website/docs/assistants.md
@@ -3,6 +3,14 @@ import TabItem from '@theme/TabItem';
 
 # /assistants
 
+:::warning Deprecation Notice
+
+OpenAI has deprecated the Assistants API. It will shut down on **August 26, 2026**.
+
+Consider migrating to the [Responses API](/docs/response_api) instead. See [OpenAI's migration guide](https://platform.openai.com/docs/guides/responses-vs-assistants) for details.
+
+:::
+
 Covers Threads, Messages, Assistants. 
 
 LiteLLM currently covers: 
diff --git a/docs/my-website/docs/embedding/supported_embedding.md b/docs/my-website/docs/embedding/supported_embedding.md
@@ -10,6 +10,26 @@ import os
 os.environ['OPENAI_API_KEY'] = ""
 response = embedding(model='text-embedding-ada-002', input=["good morning from litellm"])
 ```
+
+## Async Usage - `aembedding()`
+
+LiteLLM provides an asynchronous version of the `embedding` function called `aembedding`:
+
+```python
+from litellm import aembedding
+import asyncio
+
+async def get_embedding():
+    response = await aembedding(
+        model='text-embedding-ada-002',
+        input=["good morning from litellm"]
+    )
+    return response
+
+response = asyncio.run(get_embedding())
+print(response)
+```
+
 ## Proxy Usage 
 
 **NOTE**
diff --git a/docs/my-website/docs/index.md b/docs/my-website/docs/index.md
@@ -7,8 +7,8 @@ https://github.com/BerriAI/litellm
 
 ## **Call 100+ LLMs using the OpenAI Input/Output Format**
 
-- Translate inputs to provider's `completion`, `embedding`, and `image_generation` endpoints
-- [Consistent output](https://docs.litellm.ai/docs/completion/output), text responses will always be available at `['choices'][0]['message']['content']`
+- Translate inputs to provider's endpoints (`/chat/completions`, `/responses`, `/embeddings`, `/images`, `/audio`, `/batches`, and more)
+- [Consistent output](https://docs.litellm.ai/docs/supported_endpoints) - same response format regardless of which provider you use
 - Retry/fallback logic across multiple deployments (e.g. Azure/OpenAI) - [Router](https://docs.litellm.ai/docs/routing)
 - Track spend & set budgets per project [LiteLLM Proxy Server](https://docs.litellm.ai/docs/simple_proxy)
 
@@ -245,7 +245,7 @@ response = completion(
 
 </Tabs>
 
-### Response Format (OpenAI Format)
+### Response Format (OpenAI Chat Completions Format)
 
 ```json
 {
@@ -514,15 +514,22 @@ response = completion(
 LiteLLM maps exceptions across all supported providers to the OpenAI exceptions. All our exceptions inherit from OpenAI's exception types, so any error-handling you have for that, should work out of the box with LiteLLM.
 
 ```python
-from openai.error import OpenAIError
+import litellm
 from litellm import completion
+import os
 
 os.environ["ANTHROPIC_API_KEY"] = "bad-key"
 try:
-    # some code
-    completion(model="claude-instant-1", messages=[{"role": "user", "content": "Hey, how's it going?"}])
-except OpenAIError as e:
-    print(e)
+    completion(model="anthropic/claude-instant-1", messages=[{"role": "user", "content": "Hey, how's it going?"}])
+except litellm.AuthenticationError as e:
+    # Thrown when the API key is invalid
+    print(f"Authentication failed: {e}")
+except litellm.RateLimitError as e:
+    # Thrown when you've exceeded your rate limit
+    print(f"Rate limited: {e}")
+except litellm.APIError as e:
+    # Thrown for general API errors
+    print(f"API error: {e}")
 ```
 ### See How LiteLLM Transforms Your Requests
 
diff --git a/docs/my-website/docs/response_api.md b/docs/my-website/docs/response_api.md
@@ -43,6 +43,38 @@ response = litellm.responses(
 print(response)
 ```
 
+#### Response Format (OpenAI Responses API Format)
+
+```json
+{
+    "id": "resp_abc123",
+    "object": "response",
+    "created_at": 1734366691,
+    "status": "completed",
+    "model": "o1-pro-2025-01-30",
+    "output": [
+        {
+            "type": "message",
+            "id": "msg_abc123",
+            "status": "completed",
+            "role": "assistant",
+            "content": [
+                {
+                    "type": "output_text",
+                    "text": "Once upon a time, a little unicorn named Stardust lived in a magical meadow where flowers sang lullabies. One night, she discovered that her horn could paint dreams across the sky, and she spent the evening creating the most beautiful aurora for all the forest creatures to enjoy. As the animals drifted off to sleep beneath her shimmering lights, Stardust curled up on a cloud of moonbeams, happy to have shared her magic with her friends.",
+                    "annotations": []
+                }
+            ]
+        }
+    ],
+    "usage": {
+        "input_tokens": 18,
+        "output_tokens": 98,
+        "total_tokens": 116
+    }
+}
+```
+
 #### Streaming
 ```python showLineNumbers title="OpenAI Streaming Response"
 import litellm
diff --git a/docs/my-website/sidebars.js b/docs/my-website/sidebars.js
@@ -118,11 +118,83 @@ const sidebars = {
   ],
   // But you can create a sidebar manually
   tutorialSidebar: [
-    { type: "doc", id: "index" }, // NEW
+    { type: "doc", id: "index", label: "Getting Started" },
 
     {
       type: "category",
-      label: "LiteLLM AI Gateway",
+      label: "LiteLLM Python SDK",
+      items: [
+        {
+          type: "link",
+          label: "Quick Start",
+          href: "/docs/#litellm-python-sdk",
+        },
+        {
+          type: "category",
+          label: "SDK Functions",
+          items: [
+            {
+              type: "doc",
+              id: "completion/input",
+              label: "completion()",
+            },
+            {
+              type: "doc",
+              id: "embedding/supported_embedding",
+              label: "embedding()",
+            },
+            {
+              type: "doc",
+              id: "response_api",
+              label: "responses()",
+            },
+            {
+              type: "doc",
+              id: "text_completion",
+              label: "text_completion()",
+            },
+            {
+              type: "doc",
+              id: "image_generation",
+              label: "image_generation()",
+            },
+            {
+              type: "doc",
+              id: "audio_transcription",
+              label: "transcription()",
+            },
+            {
+              type: "doc",
+              id: "text_to_speech",
+              label: "speech()",
+            },
+            {
+              type: "link",
+              label: "All Supported Endpoints →",
+              href: "/docs/supported_endpoints",
+            },
+          ],
+        },
+        {
+          type: "category",
+          label: "Configuration",
+          items: [
+            "set_keys",
+            "caching/all_caches",
+          ],
+        },
+        "completion/token_usage",
+        "exception_mapping",
+        {
+          type: "category",
+          label: "LangChain, LlamaIndex, Instructor",
+          items: ["langchain/langchain", "tutorials/instructor"],
+        }
+      ],
+    },
+    {
+      type: "category",
+      label: "LiteLLM AI Gateway (Proxy)",
       link: {
         type: "generated-index",
         title: "LiteLLM AI Gateway (LLM Proxy)",
@@ -696,6 +768,7 @@ const sidebars = {
       type: "category",
       label: "Guides",
       items: [
+        "budget_manager",
         "completion/computer_use",
         "completion/web_search",
         "completion/web_fetch",
@@ -748,27 +821,6 @@ const sidebars = {
         "wildcard_routing"
       ],
     },
-    {
-      type: "category",
-      label: "LiteLLM Python SDK",
-      items: [
-        "set_keys",
-        "budget_manager",
-        "caching/all_caches",
-        "completion/token_usage",
-        "sdk_custom_pricing",
-        "embedding/async_embedding",
-        "embedding/moderation",
-        "migration",
-        "sdk_custom_pricing",
-        {
-          type: "category",
-          label: "LangChain, LlamaIndex, Instructor Integration",
-          items: ["langchain/langchain", "tutorials/instructor"],
-        }
-      ],
-    },
-
     {
       type: "category",
       label: "Load Testing",
@@ -838,6 +890,8 @@ const sidebars = {
       type: "category",
       label: "Extras",
       items: [
+        "sdk_custom_pricing",
+        "migration",
         "data_security",
         "data_retention",
         "proxy/security_encryption_faq",
