Indox Docs

Indox Services

Copy page

This page explains how the Indox services behave (Docs converter and Media converter), how storage and downloads work, and what to expect from auth, payments, and webhooks. Pair it with the Python client guide for copy-paste code.

Service Endpoints

• Auth: https://indox.org/auth
• Docs converter: https://indox.org/docs
• Media converter: https://indox.org/media
• All requests use Authorization: Bearer <INDOX_API_KEY>.

Conversion Flows

Document conversion (docs)

Use either a direct upload or a remote reference.

Code
 
res = client.docs.convert_file(
    file_path="./files/report.docx",
    target_formats=["pdf"],          # one or more output formats
    destination="aws",               # storage target
)

Code
 
res = client.docs.convert_url(
    file_url="https://example.com/report.docx",   # or s3_key="bucket/path/report.docx"
    target_formats=["pdf"],
    destination="aws",
)

Response (shape):

Code
 
{
  "id": "job_123",
  "status": "queued",
  "inputs": {"type": "upload|url|s3_key"},
  "target_formats": ["pdf"],
  "destination": "aws",
  "created_at": "...",
  "outputs": []               // populated after completion
}

Media conversion (images/video)

Code
 
res = client.media.convert_image(
    file_path="./images/photo.png",
    target_formats=["jpg", "webp"],
)

Code
 
res = client.media.convert_video(
    file_path="./videos/clip.mov",
    target_formats=["mp4"],
)

Status and polling

Use the client helper or hit the status endpoint (idempotent GET).

Code
 
status = client.media.wait_for_conversion(res["id"], timeout_seconds=180, poll_interval=2)
print(status["status"])       # queued | processing | completed | failed

Status response (shape):

Code
 
{
  "id": "job_123",
  "status": "completed",
  "outputs": [
    {
      "format": "pdf",
      "size_bytes": 120334,
      "download_url": "https://indox.org/media/api/v1/media/<id>/download/"
    }
  ],
  "error": null
}

Downloads

• Download URLs are clean (no format query needed) and end with /download/.
• Use the client to stream to disk:

Code
 
client.media.download_media(
    conversion_id=res["id"],
    output_path="./output/photo_converted.jpg",
)

• URLs are time-limited and do not expose the underlying storage location.

Storage & Retention

• Each user has a storage quota (default set by admins; visible in /me and token introspection).
• Usage counters update as conversions are stored; enforce limits before queuing large jobs.
• Files kept in the configured destination (e.g., AWS S3). Admins control retention; for paid storage tiers, do not auto-delete after 24h unless a policy is configured.
• To purge a specific user's files, filter objects in the user's namespace/prefix in the storage bucket and delete, then recalculate usage.

Payments & Upgrades

• Extra storage is purchased via Stripe Checkout.
• Recommended flow:
  1. Backend creates a Checkout Session (pending StoragePurchase record).
  2. User is redirected to Stripe; success page receives session_id.
  3. Backend listens to checkout.session.completed webhook; validates signature; marks purchase as succeeded; increases the user's storage limit.
  4. Frontend polls the purchase status using the session id or a purchase id before showing new limits.
• Configure the backend base URL for Stripe callbacks to https://indox.org/auth (or your environment host).

Webhooks

• Verify Stripe webhooks server-side with the signing secret.
• Handle at least:
  • checkout.session.completed: mark purchase succeeded and grant storage.
  • checkout.session.expired or payment_failed: mark purchase failed/canceled, do not change storage.
• Keep webhook handlers idempotent; guard against double grants.

Error Handling

• 400: invalid format, missing input, or unsupported destination.
• 401/403: invalid API key or insufficient scope.
• 404: job not found (expired or wrong id).
• 413: file too large for current tier/quota.
• 429: rate limited; back off and retry.
• 500: transient service error; retry with jitter.

Operational Notes

• Prefer wait_for_conversion for simple polling; for batch workloads, poll with exponential backoff.
• Use smaller poll_interval for images, larger for video/docs.
• Track request ids from error responses for support.
• When embedding URLs, never cache them longer than their expires_at (if returned).
• Keep client timeouts higher for video; uploads respect the configured timeout tuple.