ConverterHQDevelopers
Documentation

Platform architecture

Understand the control plane, data plane, durable Jobs, storage and event model behind ConverterHQ.

ConverterHQ separates API coordination from binary movement and conversion execution. That keeps request latency predictable while allowing large files and long-running conversions to continue independently of the original HTTP request.

Control and data planes

Durable execution architecture
ClientREST, SDK, MCP or Zapier
Control planeAuth + validation + resources
Owned FilesSigned binary transfers
Jobs + TasksDurable execution
DeliveryREST, webhook or export
File bytes and conversion execution are decoupled from the lifetime of the original HTTP request.

The public API is the control plane: it authenticates callers, validates capabilities and options, records Files, Jobs, Tasks, Workflows and delivery configuration, and returns durable identifiers. File bytes use signed object-storage transfers wherever practical. Conversion workers consume queued Tasks and write durable results back to the platform.

Resource model

Files represent durable binary assets. Jobs group a directed acyclic graph of named Tasks. Task attempts preserve physical execution history. Workflows version reusable Job definitions. Connections hold reusable cloud-storage credentials without copying secrets into every Job.

Execution lifecycle

Execution lifecycle
client → API → validate capability/options
             ↓
           Job
             ↓
      ready Task queue
             ↓
          worker
             ↓
       output File(s)
          ↙       ↘
   webhook       realtime
       ↓
 authoritative REST state

REST remains authoritative. Webhooks are durable at-least-once delivery for automation. WebSockets and SSE are low-latency projections for user interfaces.

Design implications

Prefer asynchronous Jobs for production pipelines, signed transfers for large files, idempotency keys around create operations, webhook verification before side effects, and request IDs in logs. Use synchronous waiting only as a convenience layer over the same durable execution model.