Getting Started for Developers

Perspect exposes the full stack it builds — content, products, orders, newsletters, databases — through a TypeScript SDK and a REST API. This guide gets you from zero to an authenticated read against your first site.

If you're not writing code and just want to build with the chat, see Getting Started.

1. Create an account and organization

1. Sign up and verify your email.
2. Create your first organization. An organization owns billing, sites, and API keys; you can invite teammates later from the admin.
3. Inside the org, create a site. The site name scopes every read and write — products, content, orders, newsletters, and users are all site-scoped.

2. Mint an API key

API keys are scoped to a single site.

1. Open your site and go to Settings → API Keys.
2. Click Create key, give it a name, and pick the permissions you need. For a read-only integration, read:* is enough.
3. Copy the key — it's shown once.

Every v2 endpoint authenticates via the X-API-Key header. The SDK sets that header for you.

3. Install the SDK

npm install perspectapi-ts-sdk

v1 (PerspectApiClient, createPerspectApiClient) is deprecated and sunsets 2026-06-01. Use the v2 client for anything new.

4. First read

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

const client = createPerspectApiV2Client({
  baseUrl: process.env.PERSPECTAPI_BASE_URL!,
  apiKey: process.env.PERSPECTAPI_API_KEY!,
});

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

If it throws a PerspectV2Error, check that baseUrl points at your Perspect deployment (no trailing slash) and the API key belongs to the same site.

5. Common next steps

• Content — list pages and posts with client.content
• Products — browse your catalog with client.products
• Orders — client.orders and client.subscriptions for checkout and customer-portal flows
• Images — pipe media URLs through image transforms for responsive, edge-optimized variants
• Data loading — the data loading guide covers pagination patterns for Remix, React Router, Next.js, and Workers

6. Calling the REST API directly

Every SDK method maps 1:1 to a REST endpoint under /api/v2:

curl -H "X-API-Key: $PERSPECTAPI_API_KEY" \
     https://api.yourdomain.com/api/v2/sites/my-site

The full reference is under API Reference.