Etiquetas
Las etiquetas clasifican proyectos, recursos o ambos. REST requiere Starter o Pro activo. Lecturas: tags:read; mutaciones: tags:write (incluye lectura). No se necesita un scope de proyectos/recursos para administrar la etiqueta.
Endpoints
| Método y ruta | Parámetros | Éxito |
|---|---|---|
GET /api/v1/tags |
Query opcional query string (nombre), limit entero 1–100 (50), offset entero ≥0 (0) |
200 {"data":[],"meta":{"limit":50,"offset":0,"total":0}} |
GET /api/v1/tags/:id |
ID positivo obligatorio | 200 {"data": etiqueta} |
POST /api/v1/tags |
JSON de creación | 201 {"data": etiqueta} |
PATCH /api/v1/tags/:id |
ID obligatorio; JSON parcial | 200 {"data": etiqueta} |
PUT /api/v1/tags/:id |
Igual que PATCH, no reemplaza campos omitidos | 200 {"data": etiqueta} |
DELETE /api/v1/tags/:id |
ID obligatorio; sin cuerpo | 200 {"data": etiqueta} eliminada |
La lista se ordena por ID ascendente. No admite filtros for_projects, for_resources, tag_ids ni external_id: filtra la aplicabilidad en el cliente. GET individual admite los parámetros comunes include=monthly_hours y from/to (fechas ISO juntas, ordenadas, máximo 3660 días), pero no añade cálculos a una etiqueta; normalmente omítelos.
Creación y actualización
| Campo | Tipo | Obligatorio al crear | Valor por defecto / validación |
|---|---|---|---|
name |
string | Sí | No vacío, máximo 100 caracteres; único por organización |
color |
string hexadecimal | No | #10B981; debe estar en la paleta inferior |
for_projects |
boolean | No | true |
for_resources |
boolean | No | false |
Al menos uno de los dos usos debe ser true. Envía ambos explícitamente para evitar depender de valores por defecto. Se normalizan espacios en el nombre y mayúsculas del color. En actualización todos son opcionales y se conservan los omitidos; {} es válido. REST también admite attrs sin duplicar atributos planos. No acepta organización ni creador como atributos.
Paleta permitida (no cualquier hexadecimal):
#E2E8F0 #64748B #1E293B #FECACA #EF4444 #991B1B
#FED7AA #F97316 #9A3412 #FEF08A #EAB308 #854D0E
#D9F99D #84CC16 #3F6212 #A7F3D0 #10B981 #065F46
#A5F3FC #06B6D4 #155E75 #BAE6FD #0EA5E9 #075985
#BFDBFE #3B82F6 #1E40AF #C7D2FE #6366F1 #3730A3
Ejemplos
Todos requieren Authorization: Bearer <API_KEY>.
POST /api/v1/tags
Content-Type: application/json
{"name":"Backend","color":"#10B981","for_projects":false,"for_resources":true}
Respuesta 201 de ejemplo:
{"data":{"id":3,"name":"Backend","color":"#10B981","for_projects":false,"for_resources":true}}
GET /api/v1/tags?query=Backend&limit=20&offset=0
GET /api/v1/tags/3
PATCH /api/v1/tags/3
Content-Type: application/json
{"for_projects":true}
DELETE /api/v1/tags/3
data tiene siempre id entero, name/color strings, for_projects/for_resources booleanos; lista usa un array de estos objetos. DELETE devuelve la representación eliminada, no 204. El borrado es destructivo: revisa su clasificación y partidas de presupuesto dependientes; no existe restore.
Errores y MCP
400 invalid_params: filtro desconocido, atributos duplicados o ID inválido. 404 not_found: etiqueta inexistente/ajena. 422 validation_error: nombre duplicado, color fuera de paleta, ambos usos false o campos inválidos. 409 conflict: otro rechazo. Todos usan errors.code y errors.detail, con errores de campo si existen; errores comunes 401/403.
MCP Pro: kordia_search con entity: "tags", kordia_get con entity: "tag" e id, y kordia_manage_tag con action: "create", "update" o "delete" y los mismos atributos planos (id para actualizar/borrar).
Relacionadas: proyectos, recursos, informes por etiqueta.