PerspectAPI TypeScript SDK

TypeScript SDK for the Perspect public API. The current API and SDK surface is v2.

v1 Is Deprecated

Do not use /api/v1, PerspectApiClient, createPerspectApiClient, or src/client/* for new code.

The v1 API and SDK surface sunsets on 2026-06-01. New integrations must use /api/v2 through PerspectApiV2Client or createPerspectApiV2Client.

Historical v1 examples have been moved to docs/v1-deprecated/sdk-readme.md for migration reference only.

Installation

npm install perspectapi-ts-sdk

Quick Start

Use the v2 subpath when you want the import itself to make the version explicit:

import { createPerspectApiV2Client } from 'perspectapi-ts-sdk/v2';

const client = createPerspectApiV2Client({
  baseUrl: 'https://api.perspect.com',
  apiKey: process.env.PERSPECTAPI_API_KEY!,
});

const site = await client.sites.get('my-site');
console.log(site.id, site.name);

The top-level package also exports v2:

import { createPerspectApiV2Client } from 'perspectapi-ts-sdk';

Common Resources

const content = await client.content.list('my-site', {
  type: 'post',
  status: 'publish',
  limit: 10,
});

const products = await client.products.list('my-site', {
  published: true,
  limit: 20,
});

const contacts = await client.contacts.list('my-site', {
  limit: 20,
});

Error Handling

import { PerspectV2Error } from 'perspectapi-ts-sdk/v2';

try {
  await client.products.get('my-site', 'prod_missing');
} catch (error) {
  if (error instanceof PerspectV2Error) {
    console.error(error.type, error.code, error.message);
  }
}

Caching

import {
  createPerspectApiV2Client,
  InMemoryCacheAdapter,
} from 'perspectapi-ts-sdk';

const client = createPerspectApiV2Client({
  baseUrl: process.env.PERSPECTAPI_BASE_URL!,
  apiKey: process.env.PERSPECTAPI_API_KEY!,
  cache: {
    adapter: new InMemoryCacheAdapter(),
    defaultTtlSeconds: 300,
  },
});

API Reference

Current SDK entry point: perspectapi-ts-sdk/v2
Current REST base path: /api/v2
Public docs: https://perspect.com/docs/sdk/typescript/v2-client
LLM docs: https://perspect.com/llms.txt

Migration

If you are maintaining existing v1 code, migrate it before 2026-06-01. v1 runtime responses include Deprecation, Sunset, Warning, Link, and X-Perspect-Deprecation-Notice headers, and v1 SDK constructors emit a warning.