Registros

Agregue un comentario o registro de actividad a una tarea u objetivo, enumere registros y elimine registros individuales. Cualquiera que pueda acceder a la pista también puede leer y agregar sus registros; los registros no llevan una ACL separada.

accountId se resuelve a partir del token de autenticación y nunca se pasa en la solicitud. El espacio de trabajo activo proviene del token o del parámetro de consulta workspaceId. Agregar y eliminar registros es gratis; enumerar registros cuesta 1 crédito.

Crear un registro

POST /v1/logs
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "trackId": "00000000-0000-4000-8000-000000000010",
  "kind": "comment",
  "content": "Blocked on missing test fixtures.",
  "metadata": { "source": "ci", "runId": "build-184" },
  "idempotencyKey": "00000000-0000-4000-8000-000000000001"
}

trackId es obligatorio y debe ser un UUID de tarea u objetivo. Se requiere content y se recorta antes de la validación.

kind es uno de:

comment es el valor predeterminado. El tipo interno system está reservado para entradas generadas por la plataforma y no se puede escribir a través del público API.

metadata acepta un objeto JSON opcional, con un límite de 16 KB una vez serializado. En su lugar, coloque detalles más grandes legibles por humanos en content. idempotencyKey es opcional; pase un UUID al volver a intentar una solicitud de creación de forma segura. La reutilización de una clave de idempotencia devuelve el registro existente a menos que ese registro se haya eliminado, en cuyo caso API devuelve 409.

Devuelve 201:

{
	"log": {
		"id": "00000000-0000-4000-8000-000000000020",
		"entryId": "00000000-0000-4000-8000-000000000010",
		"userId": "user_123",
		"authorName": "Ada",
		"kind": "comment",
		"content": "Blocked on missing test fixtures.",
		"metadata": { "source": "ci", "runId": "build-184" },
		"idempotencyKey": "00000000-0000-4000-8000-000000000001",
		"createdAt": "2026-07-07T10:15:00.000Z"
	},
	"type": "task"
}

Listar registros para una pista

GET /v1/logs?trackId=<trackId>&order=desc&cursor=<logId>
Authorization: Bearer <token>

trackId limita la lectura a los registros de una pista y siempre refleja la ACL actual de esa pista. Agregue authorId=<userId> para mostrar solo los registros de un autor visible en esa pista.

Listar el feed de actividades

Omita trackId para obtener un feed de actividad en cada pista a la que puede acceder actualmente:

GET /v1/logs?authorId=<userId>&order=desc&cursor=<logId>
Authorization: Bearer <token>

authorId funciona con o sin trackId. Si el autor solicitado está fuera de lo que la persona que llama puede ver, la respuesta está vacía en lugar de filtrar si ese autor escribió registros.

Los resultados se ordenan primero por los más nuevos de forma predeterminada (order=desc). Utilice order=asc para reproducción cronológica o, con cursor, para recuperar registros añadidos después de un registro conocido. Pase el nextCursor de la respuesta anterior como cursor con el mismo order para recuperar la página siguiente.

{
	"logs": [
		{
			"id": "00000000-0000-4000-8000-000000000020",
			"entryId": "00000000-0000-4000-8000-000000000010",
			"userId": "user_123",
			"authorName": "Ada",
			"kind": "comment",
			"content": "Blocked on missing test fixtures.",
			"metadata": { "source": "ci", "runId": "build-184" },
			"idempotencyKey": "00000000-0000-4000-8000-000000000001",
			"createdAt": "2026-07-07T10:15:00.000Z"
		}
	],
	"type": "task",
	"total": 1,
	"hasNext": false,
	"nextCursor": null
}

type se incluye cuando se configura trackId. Las respuestas del feed cruzado lo omiten porque los resultados pueden abarcar tareas y objetivos.

La fuente cruzada (cuando se omite trackId) está respaldada por una instantánea de ACL tomada cuando se escribió cada registro, no una nueva verificación en vivo de la ACL actual de la pista; si luego lo eliminan de una pista, es posible que los registros que ya podía ver allí aún aparezcan en esta fuente (una solicitud con trackId configurada siempre refleja la ACL en vivo de esa pista y no se ve afectada).

Cada registro incluye userId y authorName resueltos para la persona que llama. Un autor fuera de lo que la persona que llama ya puede ver, por ejemplo alguien que desde entonces abandonó el espacio de trabajo, se devuelve como "unknown" para ambos campos en lugar de filtrar su identificación de cuenta.

Eliminar un registro

DELETE /v1/logs/:logId
Authorization: Bearer <token>

Devuelve 200:

{
	"deleted": true,
	"type": "task"
}

Los autores pueden eliminar sus propios registros; El creador de una pista puede eliminar cualquier registro de esa pista. Los registros eliminados se omiten en futuras respuestas de la lista. Al eliminar un registro desconocido o ya eliminado se devuelve 404.

Costo

Consulte Créditos para ver la tabla completa.

Errores comunes

• Utilice un UUID de seguimiento en REST trackId; Los comandos de registro CLI y MCP también aceptan una URL que contiene el UUID de tarea o objetivo.
• Mantenga order sin cambios al pasar nextCursor a la siguiente solicitud de lista.
• Utilice metadata únicamente para campos compactos legibles por máquina; Las explicaciones extensas pertenecen a content.