A typed TypeScript SDK for your tasks and goals
Build the automation yourself: a cron job that plans the week, a backend that files support requests as tasks, or your own agent. @perspectask/sdk gives you every endpoint as a typed method with autocomplete, and errors come back as values you check, not exceptions you forget to catch.
What is the PerspecTask SDK?
@perspectask/sdk is the official TypeScript client for the PerspecTask API, generated from its OpenAPI spec with a thin hand-written layer on top: pt.tasks.list, get, create and update. Every call returns { data, error }. It also exports Zod Mini schemas for every request, generated from the same spec, so you can validate input before it leaves your code or turn the schemas into JSON Schema for your own tools. It runs on Node 20+ and is meant for server-side code, because your key is a secret.
import PerspecTask from '@perspectask/sdk';
const pt = new PerspecTask({ apiKey: process.env.PERSPECTASK_API_KEY! });
// Open work under one goal, as a tree
const { data: goal, error } = await pt.tasks.get('a3f', { tree: true });
if (error || !goal) throw new Error(JSON.stringify(error));
// Add a subtask due this week
await pt.tasks.create({
title: 'Draft the launch post',
deadline: 'this week',
parent_id: goal.id,
});Install with npm install @perspectask/sdk. The same short ids and deadline tokens work here as in the CLI and the API.
Where the SDK fits
Scripts and cron
A Monday script that lists open tasks with deadline this week and posts a summary to Slack, or one that rolls unfinished daily tasks over to tomorrow.
Your own backend
Create tasks from form submissions, webhooks or support tickets, attached to the right parent goal with parent_id, and read the completion percentage back for a dashboard.
Custom agents
Give a model your own tool layer: convert the exported Zod schemas to JSON Schema and you have tool definitions that match the API exactly. That is how @perspectask/mcp is built.
Frequently asked questions
- Is there a TypeScript SDK for a task management API?
- Yes. @perspectask/sdk is the official typed client for the PerspecTask API. It covers listing, reading, creating and updating tasks, with types and Zod schemas generated from the OpenAPI spec so they always match the server.
- How does the SDK handle errors?
- Every method returns an object with data and error instead of throwing on an HTTP error. Check error first: it holds the API response body, for example an ambiguous short id or a missing scope, so your code can react to the specific problem.
- Can I use the SDK in the browser?
- You should not. The pt_live_ API key is a secret that grants access to your tasks, so the SDK is meant for server-side code: scripts, backends, serverless functions, cron jobs and agents.
- Does the SDK work with encrypted tasks?
- Only with plaintext ones. End-to-end encrypted tasks are decrypted only in the PerspecTask app with your password, so the API, and therefore the SDK, cannot read or change them. They are left out of lists by default; pass includeEncrypted: true to get them as placeholders with encrypted set to true and no title or description, and tree views keep an encrypted task when it sits above a plaintext one, so you can still see the path.
- Is the PerspecTask SDK free?
- Yes. The SDK is free and Apache-2.0 licensed, and PerspecTask is free to start with API keys available on the free plan.
Build on your own task tree
Create a free scoped key, npm install @perspectask/sdk, and automate your goals from your own code.