Saltar al contenido principal

API v1

Los recursos v1 cuelgan directamente del cliente: client.projects, client.workItems, client.cycles, etc. Cada llamada con ámbito de workspace recibe primero el slug del workspace, y luego el id del proyecto donde la URL tiene uno. A diferencia de v2, aquí project es el UUID del proyecto, y las clases más antiguas llaman al método de eliminación delete o del (sigue la lista de métodos que muestre tu editor).

import { PlaneClient } from "@hoyasumii/plane";

const client = new PlaneClient({ apiKey: "your-api-key" });

const projects = await client.projects.list("workspace-slug");

const project = await client.projects.create("workspace-slug", {
  name: "My Project",
  description: "A new project",
});

const item = await client.workItems.create("workspace-slug", project.id, { name: "First task" });
await client.workItems.comments.create("workspace-slug", project.id, item.id, { comment_html: "<p>Hello</p>" });

// Un work item por su clave humana, en todo el workspace.
const byKey = await client.workItems.retrieveByIdentifier("workspace-slug", "ENG-12");

Recursos​

  • Projects: gestión y organización de proyectos
  • WorkItems: gestión de tareas, con CRUD completo
  • WorkItemTypes: definición y gestión de tipos de work item personalizados
  • WorkItemProperties: propiedades personalizadas de work items
  • Labels: categorización y etiquetado de tareas
  • States: gestión de estados del flujo de trabajo
  • Users: gestión de usuarios y perfiles
  • Roles: definiciones de roles de workspace y proyecto (solo lectura)
  • Estimates: estimaciones de proyecto y puntos de estimación
  • Modules: organización de funcionalidades y gestión de módulos
  • Cycles: gestión de sprints e iteraciones
  • Customers: gestión y operaciones de clientes
  • Pages: gestión de páginas de workspace y de proyecto
  • Links: enlaces y relaciones de work items
  • Workspace: operaciones a nivel de workspace
  • Epics: gestión y organización de epics
  • Intake: gestión de formularios y solicitudes de admisión
  • Stickies: gestión de notas adhesivas (stickies)
  • Teamspaces: gestión de teamspaces
  • Milestones: seguimiento y gestión de hitos
  • Initiatives: gestión de iniciativas
  • WorkspaceTemplates: plantillas de work item, proyecto y página a nivel de workspace
  • WorkspaceWorkItemTypes: gestión de tipos de work item a nivel de workspace, con vínculos de propiedades
  • WorkspaceWorkItemProperties: gestión de propiedades personalizadas a nivel de workspace, con opciones
  • WorkspaceProjectLabels: gestión de labels de proyecto a nivel de workspace
  • WorkspaceProjectStates: gestión de estados de proyecto a nivel de workspace
  • WorkItemRelationDefinitions: definiciones de tipos de relación de work item personalizados
  • Releases: gestión de releases con tags, labels, labels de item, changelog, comentarios, enlaces y work items
  • Collections: carpetas que agrupan páginas del workspace, con gestión de miembros y páginas
  • AgentRuns: orquestación de ejecuciones de agentes de IA y seguimiento de actividad
  • Workflows: gestión de workflows de proyecto, con adjuntos de estado, transiciones, hooks de transición, actividades y aprobaciones de work items
  • ProjectTemplates: gestión de plantillas de work item y de página por proyecto
  • Features: gestión de funcionalidades de workspace y de proyecto
  • WorkspaceStates: estados de work item (catálogo) a nivel de workspace, bajo la gobernanza del workspace — lectura en modo dual, escritura solo bajo gobernanza
  • WorkspaceWorkflows: catálogo de workflows a nivel de workspace, bajo la gobernanza del workspace, con cadena (estados), transiciones, uso, actividades y hooks de transición
  • WorkItemTypeGovernance: gobierna qué workflows puede usar un tipo de work item a nivel de workspace (modos any/constrained/required), con anclajes por proyecto y los endpoints de selección/vista previa de fallback del lado del proyecto
  • Instance: configuración y metadatos de la instancia (versión, edición, proveedores de autenticación, SMTP, límites de subida) desde GET /api/instances/

Los sub-recursos cuelgan de su padre: workItems.comments, workItems.attachments, workItems.activities, workItems.relations, workItems.workLogs, customers.properties, customers.requests, teamspaces.members, teamspaces.projects, initiatives.labels, initiatives.projects, initiatives.epics, agentRuns.activities, workItemProperties.options, workItemProperties.values, etc.

Información de la instancia​

const info = await client.instance.retrieve();
console.log(info.instance.current_version, info.config.is_smtp_configured);

Descargar adjuntos​

workItems.attachments.download resuelve la URL firmada de un adjunto y lo descarga, sin enviar la clave de API al host de almacenamiento. Con maxBytes, un archivo más grande se rechaza con AttachmentTooLargeError: de entrada cuando el almacenamiento anuncia su Content-Length, o en cuanto el cuerpo supera el límite.

import { AttachmentTooLargeError } from "@hoyasumii/plane";

try {
  const { data, contentType } = await client.workItems.attachments.download("acme", projectId, itemId, "asset-1", {
    maxBytes: 20 * 1024 * 1024,
  });
  console.log(contentType, data.length);
} catch (error) {
  if (error instanceof AttachmentTooLargeError) console.log("too large");
  else throw error;
}

Errores​

Una petición v1 fallida lanza HttpError, con el código de estado, el cuerpo de la respuesta y las cabeceras de la respuesta (en minúsculas, así que headers["retry-after"] en un 429). Consulta Errores para ver toda la jerarquía.