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.

Filtrado

GET /public/v1/tasks acepta filtros como parámetros de consulta: priority, task_status_id, state (open / closed), task_type_id, assignee_id, due_date_from / due_date_to / due_date, tag_id. Sin filtros devuelve todas las tareas del ámbito — el mismo conjunto que ves en la vista de tabla del proyecto en la aplicación web.

curl "https://api.bordio.com/public/v1/tasks?project_id=proj_6594a1b2c3d4e5f6a7b8c9d1&state=open&priority=high,critical" \
  -H "Authorization: Bearer brd_sk_live_..."

Cómo se combinan los filtros:

• Parámetros distintos → AND. state=open&priority=high devuelve tareas abiertas que además tienen prioridad alta.
• Varios valores dentro de un mismo parámetro → OR. Los valores se separan por comas: priority=high,critical coincide con cualquiera de las dos prioridades. tag_id=tag_a,tag_b coincide con tareas que tengan cualquiera de las etiquetas listadas.
• Los id usan su forma pública (task_status_…, task_type_…, user_…, tag_…). Un valor mal formado devuelve 400 validation_error; un id bien formado que no coincide con nada simplemente produce una página vacía. La excepción es project_id: un proyecto fuera del alcance de tu clave devuelve 404 not_found_error.
• priority también acepta none — tareas sin prioridad (priority=none,low = sin prioridad o low).
• assignee_id acepta el valor especial none — tareas sin responsable. Puede mezclarse con id de usuarios: assignee_id=user_6594a1b2c3d4e5f6a7b8c9d1,none (ese usuario, o nadie).
• due_date_from / due_date_to aceptan YYYY-MM-DD (interpretado como el inicio / fin de ese día, UTC) o un datetime ISO-8601 completo. Las tareas sin fecha límite nunca coinciden con un rango.
• due_date=none devuelve solo tareas sin fecha límite. No puede combinarse con due_date_from / due_date_to (400 validation_error).

Las recetas de consultas comunes (tareas sin responsable, vencidas, sin prioridad) están en Filtrado de tareas. La lista completa de parámetros con sus esquemas está en la Referencia de la API.

Limpieza de campos

Los endpoints PATCH distinguen dos cosas: un campo omitido se deja sin cambios, y un campo enviado como null limpia su valor — pero solo donde «sin valor» tiene sentido:

Endpoint	Campos que aceptan null	Efecto
PATCH /tasks/:id	priority, due_date, description, assignee_ids, reporter_ids, tag_ids	Limpia el valor (assignee_ids: null = nadie; tag_ids/reporter_ids: igual que [])
PATCH /tasks/:id/subtasks/:id	assignee_id, due_date	Quita el responsable / la fecha límite
PATCH /scheduled-events/:id	description, location, reminder_minutes_before	Limpia el texto / quita el recordatorio

Todo lo demás es non-clearable: enviar null a un campo obligatorio (title, task_status_id, start_at, …) devuelve 400 validation_error en lugar de ignorarse en silencio. Para restablecer una estimación numérica, envía 0; para limpiar el valor de un custom field concreto, envía su elemento de custom_fields con valor null.

Nota la diferencia con los filtros: en los parámetros de consulta de GET /tasks no existe el null de JSON, así que el valor especial none cumple el mismo papel (assignee_id=none, priority=none, due_date=none) — ver Filtrado de tareas.

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.