Asignaciones

Las asignaciones vinculan una pieza de formación (una categoría, módulo, tema, curso o escenario) a un usuario, equipo o a toda la organización con un plazo. Los mismos registros respaldan el flujo de asignación automática desde SARIF. Todos los endpoints están bajo /api/public/v1/assignments.

Endpoints

Método	Ruta	Scope	Propósito
GET	`/assignments`	`assignments:read`	Listar asignaciones con progreso agregado.
GET	`/assignments/{'{'}id{'}'}`	`assignments:read`	Una única asignación más el progreso por usuario.
POST	`/assignments`	`assignments:write`	Crear una asignación. Dispara `assignment.created`.
PATCH	`/assignments/{'{'}id{'}'}`	`assignments:write`	Actualizar plazo, flag de obligatoriedad, nota o estado activo.
DELETE	`/assignments/{'{'}id{'}'}`	`assignments:write`	Desactivar. Los registros de progreso se conservan.

Vocabulario de destinatario y contenido

Cada asignación incluye un par assigneeType + assigneeId y una terna contentArea + targetType + targetId. Los valores legales:

Campo	Valores legales	Significado de `targetId` / `assigneeId`
`assigneeType`	`user`, `team`, `org`	Para `user` y `team`, el `assigneeId` es el UUID correspondiente. Para `org`, el id es el de tu organización.
`contentArea`	`practice`, `learn`	`practice` son retos prácticos; `learn` son cursos y escenarios.
`targetType` para `practice`	`category`, `module`, `topic`	Slug en cadena, por ejemplo `web`, `owasp-top-10` o `sql-injection`.
`targetType` para `learn`	`course`, `scenario`	Slug en cadena, por ejemplo `owasp-top-10-2025` o `phishing-call-2025`.
`targetType` para cualquiera de las dos áreas	`custom-course`	UUID de un curso personalizado (consulta Cursos personalizados). Los elementos del curso determinan qué temas de práctica y/o escenarios de aprendizaje se rastrean para la finalización.

Listar asignaciones

Devuelve todas las asignaciones de la organización, activas e inactivas, con agregados de progreso desnormalizados.

GET /api/public/v1/assignments
Authorization: Bearer scs_live_…

Respuesta

[
  {
    "id": "d7c8a1b2-3e45-4f67-89ab-cd0123456789",
    "contentArea": "practice",
    "assigneeType": "team",
    "assigneeId": "4f8d3e2a-71cb-4d09-9ad7-5b8c7e1f0a32",
    "assigneeName": "Payments",
    "targetType": "topic",
    "targetId": "sql-injection",
    "targetTitle": "SQL Injection",
    "deadline": "2026-06-12T23:59:59Z",
    "isMandatory": true,
    "isActive": true,
    "isOverdue": false,
    "avgProgress": 42.5,
    "totalAssignees": 12,
    "completedAssignees": 3,
    "createdAt": "2026-05-29T08:00:00Z"
  }
]

Ejemplo

curl -sS -H "Authorization: Bearer $SCH_API_KEY" \
  https://api.limeplate.com/api/public/v1/assignments

Obtener asignación

Mismos campos que la entrada de la lista, más el nombre visible de quien asignó, la nota opcional y un array de progreso por usuario apto para informes de cumplimiento.

GET /api/public/v1/assignments/{assignmentId}
Authorization: Bearer scs_live_…

Respuesta

{
  "id": "d7c8a1b2-3e45-4f67-89ab-cd0123456789",
  "contentArea": "practice",
  "assigneeType": "team",
  "assigneeId": "4f8d3e2a-71cb-4d09-9ad7-5b8c7e1f0a32",
  "assigneeName": "Payments",
  "targetType": "topic",
  "targetId": "sql-injection",
  "targetTitle": "SQL Injection",
  "deadline": "2026-06-12T23:59:59Z",
  "isMandatory": true,
  "isActive": true,
  "isOverdue": false,
  "note": "Follow-up to the May audit finding.",
  "assignedByName": "API Key: CI Ingestion",
  "avgProgress": 42.5,
  "totalAssignees": 12,
  "completedAssignees": 3,
  "createdAt": "2026-05-29T08:00:00Z",
  "userProgress": [
    {
      "userId": "b1a4d7c2-9e58-4f3a-83cd-2c6f1a90e7b4",
      "name": "Jane Smith",
      "email": "jane.smith@acme.com",
      "totalChallenges": 8,
      "completedChallenges": 8,
      "progressPercent": 100,
      "completedAt": "2026-06-04T10:18:42Z",
      "isOverdue": false
    }
  ]
}

Ejemplo

curl -sS -H "Authorization: Bearer $SCH_API_KEY" \
  https://api.limeplate.com/api/public/v1/assignments/d7c8a1b2-3e45-4f67-89ab-cd0123456789

Crear asignación

Crea la asignación y dispara assignment.created. Si el destinatario es un equipo o la organización, las filas de progreso por usuario se materializan para cada miembro en el momento de la creación, por lo que la respuesta de GET /assignments/{id} está completa desde el principio.

POST /api/public/v1/assignments
Authorization: Bearer scs_live_…
Content-Type: application/json

Cuerpo de la solicitud

Campo	Tipo	Requerido	Significado
`assigneeType`	string	sí	`user`, `team` u `org`.
`assigneeId`	uuid	sí	ID de usuario, ID de equipo o ID de organización según el tipo.
`contentArea`	string	sí	`practice` o `learn`.
`targetType`	string	sí	Consulta la tabla de vocabulario superior.
`targetId`	string	sí	Slug o id de la categoría, módulo, tema, curso o escenario.
`deadline`	ISO 8601	sí	Fecha y hora límite en UTC.
`isMandatory`	bool	no	Por defecto `true`. Las asignaciones no obligatorias no bloquean los informes de cumplimiento.
`note`	string	no	Texto libre que se muestra al destinatario en el panel.

Respuesta

{
  "id": "d7c8a1b2-3e45-4f67-89ab-cd0123456789",
  "contentArea": "practice",
  "assigneeType": "team",
  "assigneeId": "4f8d3e2a-71cb-4d09-9ad7-5b8c7e1f0a32",
  "assigneeName": "Payments",
  "targetType": "topic",
  "targetId": "sql-injection",
  "targetTitle": "SQL Injection",
  "deadline": "2026-06-12T23:59:59Z",
  "isMandatory": true,
  "isActive": true,
  "isOverdue": false,
  "avgProgress": 0,
  "totalAssignees": 12,
  "completedAssignees": 0,
  "createdAt": "2026-05-29T08:00:00Z"
}

Ejemplo

curl -sS -X POST \
  -H "Authorization: Bearer $SCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assigneeType": "team",
    "assigneeId": "4f8d3e2a-71cb-4d09-9ad7-5b8c7e1f0a32",
    "contentArea": "practice",
    "targetType": "topic",
    "targetId": "sql-injection",
    "deadline": "2026-06-12T23:59:59Z",
    "isMandatory": true,
    "note": "Follow-up to the May audit finding."
  }' \
  https://api.limeplate.com/api/public/v1/assignments

Actualizar asignación

Se puede enviar cualquier subconjunto de deadline, isMandatory, note e isActive. Los campos omitidos se dejan como están. Usa isActive: false como equivalente no destructivo a DELETE.

PATCH /api/public/v1/assignments/{assignmentId}
Authorization: Bearer scs_live_…
Content-Type: application/json

Cuerpo de la solicitud

Campo	Tipo	Significado
`deadline`	ISO 8601	Nueva fecha límite.
`isMandatory`	bool	Conmuta el flag de obligatoriedad.
`note`	string	Reemplaza la nota. Envía cadena vacía para limpiarla.
`isActive`	bool	Activa o desactiva sin afectar al progreso.

Respuesta

{
  "message": "Assignment updated"
}

Ejemplo

curl -sS -X PATCH \
  -H "Authorization: Bearer $SCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deadline": "2026-06-26T23:59:59Z",
    "note": "Extended after sprint planning."
  }' \
  https://api.limeplate.com/api/public/v1/assignments/d7c8a1b2-3e45-4f67-89ab-cd0123456789

Desactivar asignación

Pone isActive a false. La asignación deja de aparecer en la vista "Mis asignaciones" del destinatario y deja de contribuir a las métricas de cumplimiento, pero los registros de progreso histórico se conservan para que los informes de periodos pasados sigan resolviéndose.

DELETE /api/public/v1/assignments/{assignmentId}
Authorization: Bearer scs_live_…

Respuesta

{
  "message": "Assignment deactivated"
}

Ejemplo

curl -sS -X DELETE \
  -H "Authorization: Bearer $SCH_API_KEY" \
  https://api.limeplate.com/api/public/v1/assignments/d7c8a1b2-3e45-4f67-89ab-cd0123456789

Eventos de webhook

Crear una asignación vía POST /assignments dispara assignment.created una sola vez. Cuando cualquier destinatario alcanza el 100% de progreso sobre el objetivo subyacente, assignment.completed se dispara para ese usuario: para asignaciones a equipo y a organización, esto implica un evento por miembro que llega al 100%, no un evento para toda la asignación. Ambos eventos incluyen el id de la asignación y la identidad del destinatario. Suscríbete y verifica las firmas siguiendo /docs/api/webhooks.