add documents

docs/api/overview.md

@@ -0,0 +1,104 @@
+# API Reference Overview
+
+The FastGPT Python SDK provides three main client types:
+
+## Clients
+
+| Client | Sync | Async | Description |
+|--------|------|-------|-------------|
+| [`ChatClient`](chat_client.md) | ✅ | ✅ | Chat completions and conversation management |
+| [`AppClient`](app_client.md) | ✅ | ✅ | App analytics and logs |
+| `FastGPTClient` | ✅ | ✅ | Base client (usually used indirectly) |
+
+## Base Client Options
+
+All clients share these initialization parameters:
+
+```python
+from fastgpt_client import ChatClient
+
+client = ChatClient(
+    api_key="fastgpt-xxxxx",      # Required: Your API key
+    base_url="http://localhost:3000",  # Optional: API base URL
+    timeout=60.0,                 # Optional: Request timeout (seconds)
+    max_retries=3,                # Optional: Max retry attempts
+    retry_delay=1.0,              # Optional: Delay between retries (seconds)
+    enable_logging=False          # Optional: Enable request logging
+)
+```
+
+### Parameters
+
+- **api_key** (`str`): Your FastGPT API key
+- **base_url** (`str`): Base URL for the FastGPT API (default: `"http://localhost:3000"`)
+- **timeout** (`float`): Request timeout in seconds (default: `60.0`)
+- **max_retries** (`int`): Maximum number of retry attempts (default: `3`)
+- **retry_delay** (`float`): Delay between retries in seconds (default: `1.0`)
+- **enable_logging** (`bool`): Whether to enable request logging (default: `False`)
+
+## Context Manager Support
+
+All clients support context managers for automatic resource cleanup:
+
+```python
+# Synchronous
+with ChatClient(api_key="fastgpt-xxxxx") as client:
+    response = client.create_chat_completion(...)
+# Client is automatically closed
+
+# Asynchronous
+async with AsyncChatClient(api_key="fastgpt-xxxxx") as client:
+    response = await client.create_chat_completion(...)
+# Client is automatically closed
+```
+
+## Response Format
+
+All API methods return `httpx.Response` objects. You can:
+
+```python
+# Raise exception for 4xx/5xx responses
+response.raise_for_status()
+
+# Get JSON data
+data = response.json()
+
+# Get status code
+status = response.status_code
+
+# Get headers
+headers = response.headers
+```
+
+## Async Variants
+
+All synchronous clients have async equivalents:
+
+```python
+# Sync
+from fastgpt_client import ChatClient
+
+with ChatClient(api_key="...") as client:
+    response = client.create_chat_completion(...)
+
+# Async
+from fastgpt_client import AsyncChatClient
+
+async with AsyncChatClient(api_key="...") as client:
+    response = await client.create_chat_completion(...)
+```
+
+See [Async Clients](async_clients.md) for more details.
+
+## Exceptions
+
+The SDK provides specific exceptions for different error types:
+
+| Exception | Status Code | Description |
+|-----------|-------------|-------------|
+| `AuthenticationError` | 401 | Invalid or missing API key |
+| `RateLimitError` | 429 | Too many requests |
+| `ValidationError` | 422 | Invalid request parameters |
+| `APIError` | 4xx/5xx | General API errors |
+
+See [Exceptions](exceptions.md) for more details.