Indox Docs

Indox Client Reference

Copy page

This page is the definitive guide to the Indox Python client for Docs and Media. It covers setup, response shapes, status codes, and end-to-end flows you can copy into your app.

Install & Configure

Code
 
pip install indox-client

Env vars the client reads:

• INDOX_API_KEY (required)
• INDOX_DOCS_URL (default https://indox.org/docs)
• INDOX_MEDIA_URL (default https://indox.org/media)
• Optional timeout when constructing the client (number or (connect, read) tuple).

Create a client:

Code
 
from indox_client.client import IndoxClient
client = IndoxClient.from_env()
# or explicitly:
# client = IndoxClient(api_key="...", docs_base_url="...", media_base_url="...", timeout=(5, 90))

Response Shapes You’ll See

Create (Docs/Media): convert_* methods return an accepted job payload.

Code
 
{
  "job_id": "job_123",
  "id": "job_123",               // some endpoints use id
  "status": "queued",            // queued | processing | completed | failed
  "target_formats": ["pdf"],
  "destination": "aws",
  "redirect_url": null
}

Status (poll or wait):

Code
 
{
  "id": "job_123",
  "status": "completed",
  "success": true,
  "destination": "aws",
  "download_url": "/api/v1/docs/job_123/download/",
  "outputs": [
    {"format": "pdf", "size_bytes": 120334, "download_url": ".../download/?format=pdf"}
  ],
  "error": null
}

• Pending jobs return HTTP 202 with the same shape but success: false and no download_url.
• Failed jobs set success: false and include an error message/code when available.

Downloads: download_media / docs.download stream the file to disk and return the saved Path. HTTP status 200 streams the file; 404 means the job or format is unavailable; 401/403 mean the API key is missing or lacks scope.

Status Codes Cheat Sheet (server + client expectations)

• GET single (status/info/download): 200 (ready), 202 (processing), 401, 403, 404.
• POST create (convert): 202 (accepted) or 201 (synchronous), 400 (validation), 401, 403, 409 (quota/duplicate), 429 (rate limit).
• Downloads: 200, 401, 403, 404.
• Batch collect: 202, 400, 401, 403, 409.
• Deletions/hide endpoints (when enabled): 204, 401, 403, 404. The Python client treats non-success statuses as IndoxHTTPError; include status and request_id in your logs.

Example Flows

Convert a document from S3 and wait

Code
 
res = client.docs.convert_url(
    s3_key="incoming/reports/q1.xlsx",
    target_formats=["pdf", "csv"],
    destination="aws",
)
done = client.docs.wait_for_completion(res["id"], timeout_seconds=180, poll_interval=2)
print(done["status"], done.get("download_url"))

Convert an image via upload

Code
 
job = client.media.convert_image(
    file_path="./files/diagram.png",
    target_formats=["webp", "jpg"],
    destination="aws",
)
status = client.media.wait_for_conversion(job["id"], timeout_seconds=90, poll_interval=1)
client.media.download_media(
    conversion_id=job["id"],
    output_path="./out/diagram.webp",
    fmt="webp",
)

Handle errors gracefully

Code
 
from indox_client.exceptions import IndoxHTTPError, IndoxClientError

try:
    client.media.convert_video(file_path="./clips/missing.mov", target_formats=["mp4"])
except IndoxHTTPError as err:
    print("HTTP", err.status, err.payload)
    if err.request_id:
        print("Request ID:", err.request_id)  # include in support tickets
except IndoxClientError as err:
    print("Network/Client error:", err)

Field Notes & Options

• target_formats is always required; strings are normalized (e.g., "PDF", "pdf", ".pdf" all work).
• Choose one source per request: file_path or file_url or s3_key.
• destination: aws (default), google_drive, dropbox, box, onedrive.
• redirect_url: set to receive a callback/redirect after completion.
• options: pass structured JSON for engine-specific tweaks; the client will serialize for you.
• Timeouts: pass timeout=(connect, read) when building the client for large uploads/videos.
• Close sessions in long-running processes: client.close().

Where to Explore the APIs

• Auth: /api/indox-auth (sidebar)
• Docs Conversion: /api/indox-docs
• Media Conversion: /api/indox-media