docs: Add client configuration guide and update navigation

- Added `client-configuration.md` detailing setup options for `PdfRestClient`
  and `AsyncPdfRestClient`, including parameters, timeout configurations,
  custom HTTPX client usage, and headers.
- Updated `index.md` to include links to the new `getting-started.md` and
  `client-configuration.md` guides.
- Modified `mkdocs.yml` to reflect the new navigation structure.

Assisted-by: Codex

Author: datalogics-kam

docs/client-configuration.md

@@ -0,0 +1,150 @@
+# Client configuration
+
+This guide explains how to configure
+[`PdfRestClient`](api-reference.md#pdfrest.PdfRestClient) and
+[`AsyncPdfRestClient`](api-reference.md#pdfrest.AsyncPdfRestClient), including
+how SDK settings map to HTTPX behavior.
+
+## Constructor parameters
+
+Both clients support a shared baseline:
+
+- `api_key`: API key used for the `Api-Key` header. If omitted, the SDK reads
+  `PDFREST_API_KEY` from the environment.
+- `base_url`: API host (defaults to `https://api.pdfrest.com`).
+- `timeout`: `float` seconds or an
+  [`httpx.Timeout`](https://www.python-httpx.org/api/#timeout) object.
+- `headers`: default headers merged into every request.
+- `max_retries`: retry count for retryable transport/timeouts and retryable
+  HTTP status responses.
+
+Sync-only options ([`PdfRestClient`](api-reference.md#pdfrest.PdfRestClient)):
+
+- `http_client`: preconfigured
+  [`httpx.Client`](https://www.python-httpx.org/api/#client) instance to reuse.
+- `transport`: custom
+  [`httpx.BaseTransport`](https://www.python-httpx.org/advanced/transports/).
+
+Async-only options
+([`AsyncPdfRestClient`](api-reference.md#pdfrest.AsyncPdfRestClient)):
+
+- `http_client`: preconfigured
+  [`httpx.AsyncClient`](https://www.python-httpx.org/api/#asyncclient) instance
+  to reuse.
+- `transport`: custom
+  [`httpx.AsyncBaseTransport`](https://www.python-httpx.org/advanced/transports/).
+- `concurrency_limit`: controls async file-info fetch fanout in multi-file
+  operations.
+
+## Timeout configuration
+
+By default, the SDK uses an HTTPX timeout profile with a longer read timeout.
+You can override with either a single float or a full timeout object:
+
+```python
+import httpx
+from pdfrest import PdfRestClient
+
+with PdfRestClient(
+    timeout=httpx.Timeout(connect=5.0, read=180.0, write=30.0, pool=10.0)
+) as client:
+    status = client.up()
+```
+
+HTTPX references:
+
+- [Timeouts](https://www.python-httpx.org/advanced/timeouts/)
+- [API reference: `httpx.Timeout`](https://www.python-httpx.org/api/)
+
+## Using a custom HTTPX client
+
+If you need advanced HTTP behavior (custom TLS, proxies, limits, event hooks,
+or a shared connection pool), provide a preconfigured HTTPX client.
+
+```python
+import httpx
+from pdfrest import PdfRestClient
+
+http_client = httpx.Client(
+    timeout=httpx.Timeout(20.0),
+    limits=httpx.Limits(max_connections=20, max_keepalive_connections=10),
+)
+
+with PdfRestClient(http_client=http_client) as client:
+    response = client.up()
+```
+
+HTTPX references:
+
+- [Clients](https://www.python-httpx.org/advanced/clients/)
+- [Resource Limits](https://www.python-httpx.org/advanced/resource-limits/)
+- [Proxies](https://www.python-httpx.org/advanced/proxies/)
+- [SSL](https://www.python-httpx.org/advanced/ssl/)
+- [Event Hooks](https://www.python-httpx.org/advanced/event-hooks/)
+
+## Using a custom transport
+
+For low-level customization (for example test transports and custom routing),
+pass `transport=...`:
+
+```python
+import httpx
+from pdfrest import PdfRestClient
+
+transport = httpx.HTTPTransport(retries=0)
+
+with PdfRestClient(transport=transport) as client:
+    response = client.up()
+```
+
+HTTPX reference:
+
+- [Transports](https://www.python-httpx.org/advanced/transports/)
+
+## Default and per-request headers
+
+`headers=` on the client sets default headers for all calls. Endpoint methods
+also accept `extra_headers=` to override or add request-specific headers.
+
+```python
+from pdfrest import PdfRestClient
+
+with PdfRestClient(headers={"X-App-Name": "my-service"}) as client:
+    info = client.up(extra_headers={"X-Request-ID": "req-123"})
+```
+
+## `no-id-prefix` header
+
+pdfRest supports a `no-id-prefix: true` request header used for
+pdfAssistant compatibility. In the server implementation (`../PDFCloud-API/apis/security.js`),
+this causes generated IDs to omit the leading numeric prefix and return a plain
+UUIDv4 string.
+
+### How to enable it
+
+Set it as a default client header or per-request `extra_headers`:
+
+```python
+from pdfrest import PdfRestClient
+
+with PdfRestClient(headers={"no-id-prefix": "true"}) as client:
+    uploaded = client.files.create_from_paths(["./input.pdf"])
+```
+
+### Effect on `PdfRestFileID`
+
+[`PdfRestFileID`](api-reference.md#pdfrest.models.PdfRestFileID) accepts both
+forms:
+
+- prefixed: `1<uuid-v4>` or `2<uuid-v4>` (37 chars)
+- no prefix: `<uuid-v4>` (36 chars)
+
+When `no-id-prefix` is enabled, returned IDs are the 36-character no-prefix
+variant. In that case:
+
+- `file_id.prefix` is `None`
+- `file_id.uuid` is still the UUID portion
+
+This means existing SDK code that uses
+[`PdfRestFileID`](api-reference.md#pdfrest.models.PdfRestFileID) remains
+compatible with either server ID format.

docs/index.md

@@ -16,6 +16,8 @@ Useful references:
 - [pdfRest homepage](https://pdfrest.com/)
 - [API reference](https://pdfrest.com/apidocs/)
 - [API Lab (interactive testing)](https://pdfrest.com/apilab/)
+- [Getting started guide](getting-started.md)
+- [Client configuration guide](client-configuration.md)
 
 ## How this Python API relates to pdfRest
 

mkdocs.yml

@@ -37,4 +37,5 @@ markdown_extensions:
 nav:
   - Home: index.md
   - Getting Started: getting-started.md
+  - Client Configuration: client-configuration.md
   - API Reference: api-reference.md