Controlled access · API v1

TypeScript SDK · v1.0.0

Build the integration in Node.js.

The official server-side SDK for PsyMind API v1. It requires Node.js 20.11 or newer and has no runtime dependencies.

Install from npm All integration paths

Quickstart

Authenticate and create a practice.

Keep service credentials on your backend. The SDK exposes typed resources, pagination helpers, retries, idempotency, and webhook verification.

npm install @psymind/sdk
import { PsyMind, createIdempotencyKey } from "@psymind/sdk";

const apiKey = process.env.PSYMIND_API_KEY;
if (!apiKey) throw new Error("PSYMIND_API_KEY is required");
const psymind = new PsyMind({ apiKey });

const client = await psymind.clients.create({
  external_id: createIdempotencyKey("quickstart-client"),
  preferred_language: "en",
  timezone: "UTC",
  consent_status: "granted",
  consent_version: "your-valid-consent-version",
  consent_at: new Date().toISOString(),
});

const created = await psymind.practices.create(
  { client_id: client.data.id, goal: "Sleep calmly and wake rested", language: "en", generate_audio: true },
  { idempotencyKey: createIdempotencyKey("practice") },
);

const result = await psymind.practices.waitUntilReady(created.data.id);
console.log(result.data.status, result.requestId);

Resources

What is covered.

The curated client exposes organizations, practitioners, clients and context, practices and audio polling, voices, methods, assignments, outcomes, and usage. Low-level typed access covers all 75 API v1 operations, including organization-scoped usage and webhook endpoint management, test, history, and retry.

Pagination

List methods return ApiResult<T[]>. Resource .all() helpers follow opaque cursors, detect loops, enforce page limits, and can deduplicate by id.

Reliable writes

POST retries are enabled only for OpenAPI operations that declare Idempotency-Key and only when a stable key is supplied. HTTP 409 is never retried.

Errors

PsyMindError exposes code, status, requestId, retryAfter, and available details.

Webhooks

Pass the exact raw body to verifyWebhook; validate PsyMind-Signature and atomically persist processed PsyMind-Event-Id values to deduplicate retries.

Contract

Need access to the API?

The SDK follows API v1. Usage readback and webhook-management routes are part of the current public contract; access remains organization-scoped and permission-gated.

Get API Access