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
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
client → API → validate capability/options
↓
Job
↓
ready Task queue
↓
worker
↓
output File(s)
↙ ↘
webhook realtime
↓
authoritative REST stateREST 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.