ConverterHQDevelopers
Documentation

API conventions

IDs, timestamps, pagination, headers, JSON rules and HTTP semantics used consistently across ConverterHQ API v1.

ConverterHQ API v1 follows a small set of conventions across Files, Jobs, Tasks, Workflows, Webhooks, Connections and usage resources. Learning them once makes the rest of the API predictable.

Resources and identifiers

Resource IDs are opaque strings. Persist and compare them exactly as returned; never infer ownership, creation time or shard placement from an ID. Resource URLs are stable API locators, while signed upload and download URLs are temporary capabilities and must not be stored as permanent identifiers.

Time and JSON

API timestamps are UTC RFC 3339 strings. JSON field names use snake_case. Missing and null have different meanings when a schema says a field is nullable. Monetary or credit quantities use the documented numeric representation for the endpoint; clients must not derive charges from file size alone.

Pagination and ordering

List APIs use opaque cursor pagination where supported. Treat after cursors as tokens rather than offsets. Do not construct or modify a cursor. Unless an endpoint explicitly promises another ordering, consumers should not rely on database insertion order.

Cursor pagination
GET /v1/jobs?limit=50&after=cursor_...

{
  "data": [...],
  "has_more": true,
  "next_cursor": "cursor_..."
}

HTTP headers

Authorization carries the Bearer credential. Idempotency-Key protects supported create operations from ambiguous retries. Prefer: wait=N requests a bounded synchronous wait. X-Request-ID is the primary support and correlation identifier. Respect Retry-After and rate-limit metadata when present.

Compatibility rules

API v1 may add optional fields, enum values, endpoints and capabilities without a major-version change. Clients should ignore unknown response fields and avoid exhaustive enum handling unless the schema explicitly marks an enum closed. Removing or changing existing required behavior requires formal deprecation or a future major version.