ConverterHQDevelopers
API v1

API-Konventionen

HTTP-Regeln, IDs, Pagination, Zeitangaben und gemeinsame Header der API v1.

Robuste Integrationen verlassen sich auf stabile Konventionen für Statuscodes, opaque IDs, Cursor und Request-Metadaten statt auf zufällige Details einzelner Endpunkte.

HTTP und Statuscodes

Asynchrone Erzeugungen liefern 202 Accepted, solange Arbeit weiterläuft; erfolgreiche Reads 200. Fehler verwenden Problem Details plus stabilen maschinenlesbaren code.

IDs und Zeit

Behandeln Sie file_..., job_..., task_... und project_id als opaque Strings. Zeitstempel sind ISO 8601 UTC; leiten Sie keine Semantik aus der lexikografischen ID-Reihenfolge ab.

Cursor-Pagination

Listen verwenden opaque Cursor. Reichen Sie next_cursor unverändert weiter, behalten Sie Filter bei und erzeugen Sie Cursor niemals clientseitig.

Betriebsheader

Senden Sie Idempotency-Key bei wiederholbaren Creates und speichern Sie X-Request-ID. Beachten Sie Retry-After und RateLimit-* vor Wiederholungen.