ConverterHQDevelopers
API v1

Convenções da API

Regras HTTP, IDs, paginação, horários e cabeçalhos comuns da API v1.

Integrações robustas dependem de convenções estáveis para status, IDs opacos, cursores e metadados, não de detalhes acidentais de um endpoint.

HTTP e códigos de status

Criações assíncronas retornam 202 Accepted enquanto o trabalho continua; leituras bem-sucedidas usam 200. Erros seguem Problem Details com code estável.

IDs e tempo

Trate file_..., job_..., task_... e project_id como strings opacas. Horários são ISO 8601 UTC; não deduza semântica da ordem dos IDs.

Paginação por cursor

Listas usam cursores opacos. Reenvie next_cursor sem alterações, preserve filtros e nunca fabrique um cursor no cliente.

Cabeçalhos operacionais

Envie Idempotency-Key em criações repetíveis e registre X-Request-ID. Respeite Retry-After e RateLimit-* antes de repetir.