API

UTasks Developer API

Una API pública para integrar servicios externos con UTasks.

---

Primeros pasos

URL base

https://app.utasks.io/utb

Todos los endpoints empiezan por el prefijo /pub/v1/.

Autenticación

La API usa un token Bearer. Para obtener una clave, envía el comando /apikey new a @UTasksBot.

Envía la clave en la cabecera de cada solicitud:

Authorization: Bearer utb_xxxxxxxxxxxxxxxx

Comprobar la conexión

Comprueba que la clave funciona: solicita tu perfil:

GET /utb/pub/v1/profile
Authorization: Bearer utb_...

---

Endpoints

Perfil

GET /pub/v1/profile

Devuelve el perfil del propietario de la clave de API. Útil para comprobar la conexión.

Respuesta 200 – objeto PubProfileModel

{
  "userId": "abc123",
  "userName": "ivan",
  "title": "Ivan Petrov",
  "role": "PRO",
  "roleExpireDate": "2025-12-31T00:00:00Z",
  "locale": "ru",
  "timeZone": "Europe/Moscow",
  "timeZoneId": 3
}

---

Proyectos

GET /pub/v1/projects

Proyectos de los que el usuario actual es miembro.

Respuesta 200 – array de PubProjectModel

---

GET /pub/v1/projects/{id}

Obtener un proyecto por ID. Solo para los proyectos de los que el usuario es miembro.

Parámetros de ruta

Parámetro	Tipo	Obligatorio	Descripción
id	string	✓	ID del proyecto

Respuesta 200 – objeto PubProjectModel

---

GET /pub/v1/projects/{id}/users

Miembros del proyecto con su estado. Solo para los proyectos de los que el usuario es miembro.

Parámetros de ruta

Parámetro	Tipo	Obligatorio	Descripción
id	string	✓	ID del proyecto

Respuesta 200 – array de PubProjectUserModel

---

Tareas

GET /pub/v1/tasks

Las tareas del usuario actual, por ámbito o por proyecto.

Parámetros de consulta

Parámetro	Tipo	Descripción
scope	PubTaskScope	Ámbito de las tareas (All por defecto). Se ignora si se indica projectId
projectId	string	ID del proyecto; requiere ser miembro activo
completed	boolean	true: devolver las tareas completadas en lugar de las abiertas
q	string	Texto de búsqueda (busca en los títulos)

Respuesta 200 – array de PubTaskModel

Ejemplo

GET /utb/pub/v1/tasks?scope=Today
Authorization: Bearer utb_...

GET /utb/pub/v1/tasks?projectId=abc123&completed=false
Authorization: Bearer utb_...

---

POST /pub/v1/tasks

Crear una tarea en un proyecto o en la «Bandeja de entrada» personal. Envía las mismas notificaciones al mensajero que las tareas creadas en la app.

Cuerpo de la solicitud – PubCreateTaskRequest

Respuesta 200 – objeto PubTaskModel

Ejemplo

{
  "title": "Preparar un informe",
  "description": "Informe de métricas trimestrales",
  "projectId": "abc123",
  "planDate": "2025-08-01T09:00:00Z",
  "dueDate": "2025-08-05T18:00:00Z",
  "priority": "High",
  "assigneeIds": ["user1", "user2"]
}

---

GET /pub/v1/tasks/{id}

Obtener una tarea por ID.

Parámetros de ruta

Parámetro	Tipo	Obligatorio	Descripción
id	string	✓	ID de la tarea

Respuesta 200 – objeto PubTaskModel

---

PATCH /pub/v1/tasks/{id}

Actualización parcial de una tarea. Solo se actualizan los campos que envías (distintos de null). Una lista assigneeIds vacía quita a todos los asignados.

Parámetros de ruta

Parámetro	Tipo	Obligatorio	Descripción
id	string	✓	ID de la tarea

Cuerpo de la solicitud – PubUpdateTaskRequest

Respuesta 200 – objeto PubTaskModel

Ejemplo: cambiar el estado y la prioridad

{
  "status": "InProgress",
  "priority": "Highest"
}

Ejemplo: borrar la fecha prevista

{
  "clearPlanDate": true
}

---

DELETE /pub/v1/tasks/{id}

Eliminar una tarea. Permitido al autor de la tarea y a los administradores del proyecto.

Parámetros de ruta

Parámetro	Tipo	Obligatorio	Descripción
id	string	✓	ID de la tarea

---

POST /pub/v1/tasks/{id}/complete

Marcar una tarea como completada. El autor cierra toda la tarea; un asignado marca solo su parte: la tarea se cierra del todo cuando todos los asignados han completado la suya. Disponible para el autor y los asignados.

Parámetros de ruta

Parámetro	Tipo	Obligatorio	Descripción
id	string	✓	ID de la tarea

---

POST /pub/v1/tasks/{id}/uncomplete

Reabrir una tarea completada para todos los participantes; el estado vuelve a New. Disponible para el autor y los asignados.

Parámetros de ruta

Parámetro	Tipo	Obligatorio	Descripción
id	string	✓	ID de la tarea

---

GET /pub/v1/tasks/{id}/history

Historial de cambios y comentarios de la tarea, por defecto del más antiguo al más reciente.

Parámetros de ruta

Parámetro	Tipo	Obligatorio	Descripción
id	string	✓	ID de la tarea

Parámetros de consulta

Parámetro	Tipo	Descripción
filter	string	Filtro de entradas del historial
sort	string	Orden de las entradas

Respuesta 200 – array de PubTaskHistoryItemModel

---

POST /pub/v1/tasks/{id}/attachassignee

Añadir al usuario actual (el propietario de la clave de API) como asignado de la tarea.

Parámetros de ruta

Parámetro	Tipo	Obligatorio	Descripción
id	string	✓	ID de la tarea

---

POST /pub/v1/tasks/{id}/publish

Publicar la ficha de la tarea como mensaje en el chat del proyecto (en los proyectos públicos) o en el chat personal del autor.

Parámetros de ruta

Parámetro	Tipo	Obligatorio	Descripción
id	string	✓	ID de la tarea

---

POST /pub/v1/tasks/{id}/comments

Añadir un comentario de texto a una tarea.

Parámetros de ruta

Parámetro	Tipo	Obligatorio	Descripción
id	string	✓	ID de la tarea

Cuerpo de la solicitud – PubCommentRequest

{
  "text": "Hecho, revísalo, por favor"
}

---

Modelos de datos

PubProfileModel

Perfil del usuario propietario de la clave de API.

Campo	Tipo	Descripción
userId	string	ID del usuario
userName	string	Nombre de usuario
title	string	Nombre visible
role	string	Plan / rol
roleExpireDate	string (ISO 8601)	Fecha de vencimiento del plan
locale	string	Idioma de la interfaz
timeZone	string	Zona horaria (IANA)
timeZoneId	number	ID de la zona horaria

---

PubProjectModel

Campo	Tipo	Descripción
id	string	ID del proyecto
name	string	Nombre del proyecto
description	string	Descripción
type	UTProjectType	Tipo de proyecto

---

PubProjectUserModel

Campo	Tipo	Descripción
id	string	ID del usuario
userName	string	Nombre de usuario
title	string	Nombre visible
status	UTUserStatus	Estado del miembro en el proyecto

---

PubUserModel

Información breve del usuario (se usa dentro de las tareas).

Campo	Tipo	Descripción
id	string	ID del usuario
userName	string	Nombre de usuario
title	string	Nombre visible

---

PubTaskModel

Campo	Tipo	Descripción
id	string	ID de la tarea
number	string	Número legible de la tarea, por ejemplo UT-12
title	string	Título de la tarea
description	string	Descripción
status	UTTaskStatus	Estado
priority	UTTaskPriority	Prioridad
projectId	string | null	ID del proyecto; null para las tareas de la «Bandeja de entrada» personal
projectName	string | null	Nombre del proyecto; null para la «Bandeja de entrada» personal
planDate	string | null	Fecha prevista (ISO 8601)
planCron	string | null	Regla de repetición de la fecha prevista
dueDate	string | null	Fecha límite (ISO 8601)
isCompleted	boolean	La tarea está completada del todo. En las tareas con varios asignados pasa a true solo cuando cada uno ha marcado su parte
completedDate	string | null	Fecha de finalización
completedUserIds	string[]	ID de los asignados que han marcado su parte como completada
personalCompleted	boolean	La tarea está completada para el usuario actual: o está completada del todo, o el usuario ha marcado su parte
author	PubUserModel	Autor de la tarea
assignees	PubUserModel[]	Asignados

---

PubCreateTaskRequest

Campo	Tipo	Obligatorio	Descripción
title	string	✓	Título de la tarea, hasta 5000 caracteres
description	string | null		Descripción, hasta 5000 caracteres
projectId	string | null		ID del proyecto; omítelo para la «Bandeja de entrada» personal
planDate	string | null		Fecha prevista (ISO 8601)
dueDate	string | null		Fecha límite; no puede ser anterior a la fecha prevista
planCron	string | null		Regla de repetición de la fecha prevista
priority	UTTaskPriority		Prioridad
assigneeIds	string[] | null		ID de los asignados. Deben ser miembros del proyecto

---

PubUpdateTaskRequest

Todos los campos son opcionales. Envía solo los que quieras cambiar.

Campo	Tipo	Descripción
title	string | null	Nuevo título, hasta 5000 caracteres
description	string | null	Nueva descripción, hasta 5000 caracteres
planDate	string | null	Nueva fecha prevista
dueDate	string | null	Nueva fecha límite; no puede ser anterior a la fecha prevista
clearPlanDate	boolean	Borrar la fecha prevista (tiene prioridad sobre planDate)
clearDueDate	boolean	Borrar la fecha límite (tiene prioridad sobre dueDate)
planCron	string | null	Nueva regla de repetición
priority	UTTaskPriority	Nueva prioridad
status	UTTaskStatus	Nuevo estado
assigneeIds	string[] | null	Nueva lista completa de asignados (un array vacío los quita a todos)

---

PubCommentRequest

Campo	Tipo	Obligatorio	Descripción
text	string	✓	Texto del comentario

---

PubCommentModel

Campo	Tipo	Descripción
text	string	Texto del comentario
createDate	string (ISO 8601)	Fecha de creación

---

PubTaskHistoryItemModel

Una entrada del historial de cambios de la tarea.

Campo	Tipo	Descripción
date	string (ISO 8601)	Fecha del evento
author	PubUserModel	Autor del cambio
comment	string	Texto del comentario (si es un comentario)
change	PubTaskHistoryChangeModel	Detalles del cambio del campo

---

PubTaskHistoryChangeModel

Campo	Tipo	Descripción
field	string	Nombre del campo cambiado
oldValue	string	Valor anterior
newValue	string	Valor nuevo

---

Enumeraciones

UTTaskStatus

Estado de la tarea.

Valor	Descripción
New	Nueva
ToDo	Por hacer
InProgress	En progreso
Resolved	Resuelta
Review	En revisión
Approved	Aprobada
Closed	Hecha

---

UTTaskPriority

Prioridad de la tarea.

Valor	Descripción
None	Sin definir
Lowest	Muy baja
Low	Baja
Medium	Media
High	Alta
Highest	Muy alta

---

UTProjectType

Tipo de proyecto.

Valor	Descripción
Private	Privado
Public	Público
Dynamic	Dinámico

---

UTUserStatus

Rol del miembro en el proyecto.

Valor	Descripción
None	Sin rol
Creator	Creador
Administrator	Administrador
Member	Miembro

---

PubTaskScope

Ámbito del filtro de tareas.

Valor	Descripción
All	Todas las tareas
Inbox	«Bandeja de entrada»
Today	Para hoy
Tomorrow	Para mañana
Week	Para esta semana
Completed	Completadas

---

Ejemplos de uso

Obtener las tareas de hoy

GET /utb/pub/v1/tasks?scope=Today
Authorization: Bearer utb_...

Crear una tarea en la «Bandeja de entrada» personal

POST /utb/pub/v1/tasks
Authorization: Bearer utb_...
Content-Type: application/json

{
  "title": "Llamar al cliente",
  "planDate": "2025-08-01T10:00:00Z",
  "priority": "High"
}

Crear una tarea en un proyecto con asignados

POST /utb/pub/v1/tasks
Authorization: Bearer utb_...
Content-Type: application/json

{
  "title": "Revisar el PR #42",
  "projectId": "proj_abc",
  "assigneeIds": ["user_1", "user_2"],
  "dueDate": "2025-08-03T18:00:00Z",
  "priority": "Medium"
}

Pasar una tarea a «En progreso»

PATCH /utb/pub/v1/tasks/task_xyz
Authorization: Bearer utb_...
Content-Type: application/json

{
  "status": "InProgress"
}

Completar una tarea

POST /utb/pub/v1/tasks/task_xyz/complete
Authorization: Bearer utb_...

Añadir un comentario

POST /utb/pub/v1/tasks/task_xyz/comments
Authorization: Bearer utb_...
Content-Type: application/json

{
  "text": "Hecho, espero tu revisión"
}

---

Códigos de error

Código	Descripción
400	Solicitud incorrecta: revisa el cuerpo de la solicitud
401	No autorizado: revisa tu clave de API
403	Prohibido: no tienes permisos suficientes para esta acción
404	Objeto no encontrado
500	Error interno del servidor

El cuerpo del error se devuelve en formato ProblemDetails:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "Title is required"
}

Conectar el servidor MCP