# What Is the @plane/services Package Used For? A Complete Guide to Plane’s API Client SDK

> Discover the @plane/services package, Plane's typed client-side SDK. This guide explains how it simplifies interaction with the Plane backend REST API for workspaces, users, and authentication.

- Repository: [Plane/plane](https://github.com/makeplane/plane)
- Tags: api-reference
- Published: 2026-08-22

---

**The `@plane/services` package is a typed client-side SDK that provides service classes for interacting with the Plane back-end REST API, centralizing HTTP logic through a base `APIService` class and exporting domain-specific services for workspaces, users, and authentication.**

The `@plane/services` package serves as the official JavaScript/TypeScript client SDK for the [makeplane/plane](https://github.com/makeplane/plane) project management platform. Located within the monorepo's `packages/services` directory, this package abstracts all low-level HTTP communication into type-safe service classes. Front-end applications use it to consume REST endpoints without manually handling Axios configurations, request URLs, or repetitive error-checking logic.

## Core Architecture of the @plane/services Package

The package implements a layered architecture where a centralized base class handles HTTP transport, while specialized subclasses manage domain-specific business logic. This pattern ensures consistent error handling and request formatting across the entire Plane web application.

### The APIService Base Class

Located in [`src/api.service.ts`](https://github.com/makeplane/plane/blob/main/src/api.service.ts), the **`APIService`** class centralizes Axios configuration and injects the base URL from `API_BASE_URL` (imported from `@plane/constants`). It exposes protected helper methods—`get()`, `post()`, `patch()`, and `delete()`—that standardize error handling and request logic. All domain services extend this class, inheriting the same HTTP client instance and interceptors.

### Domain-Specific Service Classes

Each functional area of the Plane API has a dedicated service class extending `APIService`. These include **`WorkspaceService`**, **`UserService`**, **`AuthService`**, and additional services for projects, issues, and file uploads. Every service implements high-level CRUD methods—`list()`, `retrieve()`, `create()`, `update()`, and `destroy()`—that correspond to REST endpoints. These methods return typed promises defined in `@plane/types`, ensuring compile-time safety for API responses.

## Key Service Classes and Their Responsibilities

The package organizes functionality into discrete modules, with each major domain represented by its own service file.

### WorkspaceService

The **`WorkspaceService`** class, defined in [`src/workspace/workspace.service.ts`](https://github.com/makeplane/plane/blob/main/src/workspace/workspace.service.ts), manages workspace-related operations. It provides methods for listing user workspaces, retrieving specific workspace details, and validating workspace identifiers through the `slugCheck()` method.

### UserService

Found in [`src/user/user.service.ts`](https://github.com/makeplane/plane/blob/main/src/user/user.service.ts), the **`UserService`** handles user profile retrieval and updates. It exposes methods like `updateProfile()` to modify user attributes while maintaining type safety through interfaces defined in the `@plane/types` package.

### AuthService

The **`AuthService`** class in [`src/auth/auth.service.ts`](https://github.com/makeplane/plane/blob/main/src/auth/auth.service.ts) manages authentication flows including `signIn()`, `signOut()`, and token refresh operations. This service provides a secure, typed interface for session management and credential handling.

## How to Use @plane/services in Your Application

The package exposes a clean, promise-based API that integrates directly with React components, hooks, or any client-side JavaScript code.

### Listing All Workspaces

Import `WorkspaceService` to fetch workspaces for the current authenticated user:

```tsx
import { WorkspaceService } from "@plane/services";

const workspaceService = new WorkspaceService();
workspaceService
  .list()
  .then((workspaces) => {
    // workspaces is typed as IWorkspace[]
    console.log("User workspaces:", workspaces);
  })
  .catch((err) => {
    console.error("Failed to fetch workspaces:", err);
  });

```

### Updating User Profiles

Use `UserService` to modify profile information with full TypeScript support:

```tsx
import { UserService } from "@plane/services";

const userService = new UserService();

async function updateProfile(name: string) {
  try {
    const updated = await userService.updateProfile({ first_name: name });
    console.log("Profile updated:", updated);
  } catch (e) {
    console.error("Profile update error:", e);
  }
}

```

### Validating Workspace Slugs

Check workspace identifier availability before creation:

```tsx
import { WorkspaceService } from "@plane/services";

const wsService = new WorkspaceService();

wsService
  .slugCheck("my‑team")
  .then((result) => console.log("Slug available:", result))
  .catch((e) => console.error("Slug check failed:", e));

```

### Handling Authentication

Implement login flows using the `AuthService` class:

```tsx
import { AuthService } from "@plane/services";

const auth = new AuthService();

auth
  .signIn({ email: "john@example.com", password: "secret" })
  .then(() => console.log("Signed in!"))
  .catch((err) => console.error("Login error:", err));

```

## Package Structure and Export Strategy

The `@plane/services` package uses [`src/index.ts`](https://github.com/makeplane/plane/blob/main/src/index.ts) as a central export hub, re-exporting every domain service so consumers can import directly from the package name without navigating internal folder structures. The **[`package.json`](https://github.com/makeplane/plane/blob/main/package.json)** defines the module boundaries and lists dependencies including `axios` for HTTP transport and `file-type` for file handling capabilities.

This single-entry-point design means developers can access any service using concise import statements like `import { WorkspaceService, UserService } from "@plane/services"`, while the internal implementation details remain encapsulated and free to evolve.

## Summary

- **`@plane/services`** acts as the typed client-side SDK for the Plane REST API, bridging the front-end applications with the back-end server.
- The **`APIService`** base class in [`src/api.service.ts`](https://github.com/makeplane/plane/blob/main/src/api.service.ts) centralizes Axios configuration, request methods, and error handling for all derived services.
- Domain services like **`WorkspaceService`**, **`UserService`**, and **`AuthService`** provide high-level CRUD methods that return typed promises from `@plane/types`.
- The **[`src/index.ts`](https://github.com/makeplane/plane/blob/main/src/index.ts)** export hub enables clean imports from `@plane/services`, abstracting the internal file structure and simplifying maintenance.

## Frequently Asked Questions

### What is the @plane/services package used for?

The `@plane/services` package provides a type-safe client SDK that Plane's front-end applications use to communicate with the back-end REST API. It wraps low-level HTTP calls in service classes, allowing developers to interact with workspaces, users, and authentication endpoints using typed JavaScript/TypeScript methods rather than raw fetch requests.

### How does the APIService class handle HTTP configuration?

The `APIService` class, defined in [`src/api.service.ts`](https://github.com/makeplane/plane/blob/main/src/api.service.ts), serves as the foundation for all domain services. It configures the Axios instance with the base URL from `API_BASE_URL`, sets up request interceptors, and exposes protected methods (`get`, `post`, `patch`, `delete`) that standardize error handling and request formatting across the entire package.

### What types of operations do the domain services support?

Each domain service supports standard CRUD operations through methods like `list()`, `retrieve()`, `create()`, `update()`, and `destroy()`. Additionally, services expose domain-specific methods such as `WorkspaceService.slugCheck()` for validation or `AuthService.signIn()` for authentication flows, all returning typed promises defined in the `@plane/types` package.

### How do I import services from the @plane/services package?

You can import any service directly from the package root due to the centralized export pattern in [`src/index.ts`](https://github.com/makeplane/plane/blob/main/src/index.ts). For example, use `import { WorkspaceService, UserService } from "@plane/services"` to access the classes without specifying individual file paths, keeping import statements concise and resilient to internal refactoring.