# 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.