ConverterHQDevelopers
API v1

Konwencje API

Reguły HTTP, identyfikatory, paginacja, czas i wspólne nagłówki API v1.

Solidna integracja opiera się na stabilnych konwencjach dla statusów, opaque IDs, cursorów i metadanych, nie na przypadkowych szczegółach endpointu.

HTTP i status codes

Asynchroniczne create zwracają 202 Accepted, gdy praca trwa; udane odczyty 200. Błędy używają Problem Details i stabilnego code.

ID i czas

Traktuj file_..., job_..., task_... i project_id jako opaque strings. Timestampy są ISO 8601 UTC; nie wyciągaj znaczenia z kolejności ID.

Paginacja cursor

Listy używają opaque cursorów. Przekazuj next_cursor bez zmian, zachowuj filtry i nie twórz cursora po stronie klienta.

Nagłówki operacyjne

Wysyłaj Idempotency-Key przy powtarzalnych create i zapisuj X-Request-ID. Respektuj Retry-After i RateLimit-* przed retry.