SDK Guide

The Pixelated Empathy SDKs are auto-generated from ourOpenAPI 3.1 specification usingopenapi-generator. The generation pipeline runs automatically in CI whenever the spec changes.

Available SDKs

TypeScript SDK

Installation

npm install @pixelated-empathy/auto-sdk
# or
pnpm add @pixelated-empathy/auto-sdk

Configuration

import {
  Configuration,
  DefaultApi,
} from '@pixelated-empathy/auto-sdk';

const config = new Configuration({
  // Required: API key from /admin/api-keys
  apiKey: process.env.PIXELATED_API_KEY,

  // Optional: Override base URL (default: https://api.pixelatedempathy.com)
  basePath: process.env.PIXELATED_API_URL ?? 'https://api.pixelatedempathy.com',

  // Optional: Request timeout (default: 30000ms)
  timeout: 30000,

  // Optional: Retry configuration
  retry: {
    maxRetries: 3,
    initialDelayMs: 500,
    maxDelayMs: 5000,
    retryOnStatus: [429, 500, 502, 503],
  },
});

const client = new DefaultApi(config);

Using the Client

// All methods are typed with auto-generated interfaces
const health = await client.getHealth();
//    ^? { status: string; version: string; timestamp: string }

const search = await client.searchContent({
  q: 'anxiety',
  limit: 10,
  offset: 0,
});
//    ^? { data: SearchResult[]; total: number; page: number }

// Type-safe request and response objects
const memory = await client.createMemory({
  userId: 'user-123',
  content: 'Session notes',
  metadata: { sessionType: 'cbt' },
});
//    ^? { id: string; userId: string; content: string; createdAt: string }

Python SDK

Installation

pip install pixelated-empathy-sdk
# or
uv add pixelated-empathy-sdk

Configuration

import os
from pixelated_empathy_sdk import Configuration, DefaultApi

config = Configuration(
    api_key=os.environ["PIXELATED_API_KEY"],
    host=os.environ.get("PIXELATED_API_URL", "https://api.pixelatedempathy.com"),
    timeout=30000,
)

client = DefaultApi(config)

Using the Client

# All methods are typed with auto-generated interfaces
health = client.get_health()
print(health.status, health.version)

search = client.search_content(q="anxiety", limit=10, offset=0)
for result in search.data:
    print(result.id, result.title)

# Type-safe request and response objects
memory = client.create_memory(
    user_id="user-123",
    content="Session notes",
    metadata={"sessionType": "cbt"},
)
print(memory.id, memory.created_at)

Hand-Written SDK (Legacy)

A hand-written TypeScript SDK (@pixelated-empathy/sdk) is also available at packages/pixelated-sdk/. It provides additional features like Zod schema validation and a fluent API. The auto-generated SDK is recommended for new integrations as it stays in sync with the OpenAPI spec automatically.

SDK Generation Pipeline

The SDK generation pipeline runs in CI at.github/workflows/sdk-generation.yml. It:

1. Validates the OpenAPI spec with Spectral linting
2. Downloads openapi-generator-cli v7.12.0
3. Generates TypeScript (typescript-fetch) and Python SDKs
4. Builds and type-checks both packages
5. Publishes to npm and PyPI on main branch
6. Uploads generated code as CI artifacts

To regenerate SDKs manually:

./scripts/ci/generate-sdks.sh        # Generate only
./scripts/ci/generate-sdks.sh --publish  # Generate + publish

Related

• Getting Started Guide
• Code Examples
• Interactive API Reference