Convenciones

Convención de mayúsculas/minúsculas de campos

Todos los campos de solicitud y respuesta usan snake_case — por ejemplo, due_date, task_status_id.

Envoltorios de respuesta

Las respuestas exitosas se envuelven en un envoltorio data:

{ "data": { "id": "task_6a2918cff58b0a1d387866ee" } }

Los endpoints de lista añaden un objeto pagination:

{
  "data": [ /* … */ ],
  "pagination": { "next_cursor": "…", "has_more": true }
}

Los errores usan un envoltorio separado — consulta Errores.

Paginación

Los endpoints de lista se paginan mediante cursor. Pasa el next_cursor de la respuesta anterior para obtener la siguiente página; has_more te indica cuándo detenerte. Trata el cursor como opaco.

Idempotencia

Las solicitudes POST (creaciones) aceptan un encabezado Idempotency-Key. Envía una clave única (de hasta 255 caracteres — un UUID funciona bien) para que una solicitud reintentada no pueda crear un duplicado:

curl -X POST https://api.bordio.com/public/v1/tasks \
  -H "Authorization: Bearer brd_sk_live_..." \
  -H "Idempotency-Key: 6a2918cf-f58b-0a1d-3878-66ee00000001" \
  -H "Content-Type: application/json" \
  -d '{ "title": "New task" }'

Cómo se comporta:

• Misma clave, mismo cuerpo → se devuelve el resultado guardado original; no se crea nada nuevo.
• Misma clave, cuerpo diferente → 409 conflict_error (already_exists).
• Misma clave mientras la primera solicitud aún está en curso → 409 conflict_error — reintenta cuando la primera haya terminado.
• Las claves se recuerdan durante 24 horas y luego expiran — reutilizar una clave después de ese tiempo se trata como una solicitud completamente nueva.
• Una clave está limitada a su endpoint (y espacio de trabajo): la misma clave en un endpoint diferente es independiente.
• Solo POST es idempotente mediante este encabezado. PATCH/DELETE no lo son — un PATCH es naturalmente seguro de repetir, ya que establece los campos a los valores que envías.