Skip to main content

API v1

The v1 resources hang directly off the client: client.projects, client.workItems, client.cycles, and so on. Every workspace-scoped call takes the workspace slug first, then the project id where the URL has one. Unlike v2, project here is the project's UUID, and the older classes spell the removal method delete or del (follow the method list your editor shows).

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>" });

// A work item by its human key, across the workspace.
const byKey = await client.workItems.retrieveByIdentifier("workspace-slug", "ENG-12");

Resources​

  • Projects: Project management and organization
  • WorkItems: Issue and task management with full CRUD operations
  • WorkItemTypes: Custom work item type definitions and management
  • WorkItemProperties: Custom properties for work items
  • Labels: Issue categorization and tagging
  • States: Workflow state management
  • Users: User management and profiles
  • Roles: Workspace and project role definitions (read-only)
  • Estimates: Project estimates and estimate points
  • Modules: Feature organization and module management
  • Cycles: Sprint and iteration management
  • Customers: Customer management and operations
  • Pages: Workspace and project page management
  • Links: Work item linking and relationships
  • Workspace: Workspace-level operations
  • Epics: Epic management and organization
  • Intake: Intake form and request management
  • Stickies: Stickies management
  • Teamspaces: Teamspace management
  • Milestones: Milestone tracking and management
  • Initiatives: Initiative management
  • WorkspaceTemplates: Workspace-level work item, project, and page templates
  • WorkspaceWorkItemTypes: Workspace-level work item type management with property links
  • WorkspaceWorkItemProperties: Workspace-level custom property management with options
  • WorkspaceProjectLabels: Workspace-level project label management
  • WorkspaceProjectStates: Workspace-level project state management
  • WorkItemRelationDefinitions: Custom work item relation type definitions
  • Releases: Release management with tags, labels, item labels, changelog, comments, links, and work items
  • Collections: Folders that group workspace pages, with member and page management
  • AgentRuns: AI agent run orchestration and activity tracking
  • Workflows: Project workflow management with state attachments, transitions, transition hooks, activities, and work item approvals
  • ProjectTemplates: Work item and page template management per project
  • Features: Workspace and project features management
  • WorkspaceStates: Workspace-level (catalog) work-item states under workspace governance — dual-mode reads, governed-only writes
  • WorkspaceWorkflows: Workspace-level workflow catalog under workspace governance, with chain (states), transitions, usage, activities, and transition hooks
  • WorkItemTypeGovernance: Governs which workflows a workspace-level work item type may use (any/constrained/required modes), with per-project pins and the project-side pick/fallback-preview endpoints
  • Instance: Instance configuration and metadata (version, edition, auth providers, SMTP, upload limits) from GET /api/instances/

Sub-resources hang off their parent: 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, and so on.

Instance information​

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

Downloading attachments​

workItems.attachments.download resolves an attachment's signed URL and downloads it, without sending the API key to the storage host. With maxBytes, a larger file is refused with AttachmentTooLargeError: up front when storage announces its Content-Length, otherwise as soon as the body passes the cap.

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;
}

Errors​

A failed v1 request raises HttpError, with the status code, the response body and the response headers (lower-cased, so headers["retry-after"] on a 429). See Errors for the whole hierarchy.