ConverterHQDevelopers
API v1

Convenzioni API

Regole HTTP, ID, paginazione, tempi e header comuni all’API v1.

Un’integrazione robusta dipende da convenzioni stabili per status, ID opachi, cursori e metadati, non da dettagli accidentali di un endpoint.

HTTP e codici di stato

Le creazioni asincrone restituiscono 202 Accepted mentre il lavoro continua; le letture riuscite 200. Gli errori usano Problem Details con code stabile.

ID e tempo

Tratta file_..., job_..., task_... e project_id come stringhe opache. I timestamp sono ISO 8601 UTC; non dedurre significato dall’ordine degli ID.

Paginazione a cursore

Le liste usano cursori opachi. Riutilizza next_cursor senza modificarlo, conserva i filtri e non costruire cursori lato client.

Header operativi

Invia Idempotency-Key sulle create ripetibili e conserva X-Request-ID. Rispetta Retry-After e RateLimit-* prima di riprovare.