Skip to content

Client configuration

This guide explains how to configure PdfRestClient and 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 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):

Async-only options (AsyncPdfRestClient):

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:

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:

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.

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:

Using a custom transport

For low-level customization (for example test transports and custom routing), pass transport=...:

import httpx
from pdfrest import PdfRestClient

transport = httpx.HTTPTransport(retries=0)

with PdfRestClient(transport=transport) as client:
    response = client.up()

HTTPX reference:

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.

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:

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 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 remains compatible with either server ID format.