Quick Start

Get your first puzzle in under 5 minutes. This guide walks you through creating a tenant account, generating an API key, installing the TypeScript SDK, and making your first request.

Prerequisites

A Puzzle Section tenant account (register here)
Node.js 18+ and TypeScript 5.0+ (recommended)

Register Your Tenant

Sign up for a tenant account on the dashboard. Each tenant represents your organisation and scopes all API keys, users, and data.

Create Tenant Account

Generate an API Key

Navigate to Dashboard → API Keys and create a new key. Keys are prefixed to indicate their environment:

ps_live_*Production — returns real puzzles

ps_test_*Sandbox — returns sample data for development

Keep your key secret

Never expose your API key in client-side code or public repositories. Store it in environment variables and make API calls from your server.

Install the TypeScript SDK

The official TypeScript SDK provides full type safety, automatic retries with exponential backoff, and typed error classes.

bash

npm install @puzzle-section/sdk

Or with your preferred package manager:

bash

yarn add @puzzle-section/sdk

bash

pnpm add @puzzle-section/sdk

Initialise the Client

Create a client instance with your API key. The SDK sends the key via the X-API-Key header on every request.

.env

PUZZLE_SECTION_API_KEY=ps_live_xxxxxxxxxxxx

src/puzzle-client.ts

import { PuzzleSectionClient } from '@puzzle-section/sdk';

export const client = new PuzzleSectionClient({
  apiKey: process.env.PUZZLE_SECTION_API_KEY!,
});

Fetch Your First Puzzle

Every SDK method returns a ResponseWithRateLimit<T> containing data and rateLimit fields.

src/example.ts

1import { client } from './puzzle-client';
2
3// Fetch today's daily puzzles
4const { data: dailyPuzzles, rateLimit } = await client.puzzles.getDaily();
5
6console.log(dailyPuzzles);
7// [
8//   {
9//     id: '550e8400-e29b-41d4-a716-446655440000',
10//     type: 'sudoku',
11//     difficulty: 'medium',
12//     date: '2026-03-05',
13//     estimatedTime: 480,
14//     isPremium: false,
15//     data: {
16//       grid: [[0, 0, 3, ...], ...],
17//       given: [[false, false, true, ...], ...],
18//       difficulty: 'medium'
19//     },
20//     createdAt: '2026-03-04T00:00:00Z',
21//     updatedAt: '2026-03-04T00:00:00Z'
22//   },
23//   ...
24// ]
25
26console.log(rateLimit);
27// { limit: 1000, remaining: 999, reset: 1741219200 }
28
29// Filter by type and difficulty
30const { data: sudoku } = await client.puzzles.getDaily({
31  types: ['sudoku'],
32  difficulties: ['medium'],
33});
34
35// Fetch a specific puzzle by UUID
36const { data: puzzle } = await client.puzzles.getById(
37  '550e8400-e29b-41d4-a716-446655440000'
38);
39
40// List all available puzzle types
41const { data: types } = await client.puzzles.getTypes();
42console.log(types); // ['sudoku', 'wordsearch', 'crossword', ...]

You are all set

You now have a working integration. Explore the TypeScript SDK reference for the full API surface including puzzle generation, validation, health checks, and admin operations.

Quick Start

Prerequisites

Register Your Tenant

Generate an API Key

Install the TypeScript SDK

Initialise the Client

Fetch Your First Puzzle

Next Steps

TypeScript SDK Reference

Authentication

Integration Guide

API Reference