TypeScript SDK

Name: OptimoCMS SDK
Author: OptimoCMS

The official TypeScript SDK provides a type-safe, ergonomic interface for the OptimoCMS API.

Installation

npm install @optimocms/sdk

Or with yarn/pnpm:

yarn add @optimocms/sdk
pnpm add @optimocms/sdk

Requirements

Environment	Minimum version
Node.js	18.0+
TypeScript	5.0+ (optional, but recommended)
Browser	Any with ES2020 module support (Chrome 80+, Firefox 80+, Safari 14+, Edge 80+)

Module formats

The SDK ships both ESM and CJS bundles:

// ESM (recommended)
import { OptimoCMS } from '@optimocms/sdk';

// CommonJS
const { OptimoCMS } = require('@optimocms/sdk');

Client setup

import { OptimoCMS } from '@optimocms/sdk';

const cms = new OptimoCMS({
  apiKey: process.env.OPTIMOCMS_API_KEY!,
});

Configuration options

const cms = new OptimoCMS({
  apiKey: process.env.OPTIMOCMS_API_KEY!,

  // Base URL (default: https://api.optimocms.com)
  baseUrl: 'https://api.optimocms.com',

  // Request timeout in ms (default: 30000)
  timeout: 30_000,

  // Automatic retry on 429/5xx (default: 3)
  maxRetries: 3,
});

Option	Type	Default	Description
`apiKey`	`string`	—	Required. Your API key
`baseUrl`	`string`	`https://api.optimocms.com`	API base URL
`timeout`	`number`	`30000`	Request timeout in milliseconds
`maxRetries`	`number`	`3`	Max retries on rate limit or server errors

Browser usage

The SDK also works in the browser. Never use your API key directly in client-side code — create a backend proxy:

// Backend (Node.js) — /api/sites.ts
import { OptimoCMS } from '@optimocms/sdk';

const cms = new OptimoCMS({ apiKey: process.env.OPTIMOCMS_API_KEY! });

export async function GET() {
  const sites = await cms.sites.list();
  return Response.json(sites);
}

// Frontend (browser)
const response = await fetch('/api/sites');
const sites = await response.json();

Available modules

After initialization you have access to all API modules:

cms.sites       // Manage sites
cms.pages       // Page CRUD
cms.media       // Upload and manage media
cms.analytics   // Retrieve analytics
cms.ai          // AI generation and translation
cms.booking     // Bookings
cms.reservation // Reservations
cms.shop        // Products, orders, coupons
cms.loyalty     // Loyalty points
cms.webhooks    // Webhook configuration
cms.forms       // Form submissions
cms.push        // Push notifications
cms.reviews     // Reviews
cms.recruitment // Job listings
cms.batch       // Bulk operations
cms.jobs        // Async job polling

TypeScript types

All request and response types are fully typed and exported:

import type {
  Site,
  SiteSummary,
  Page,
  PageDetail,
  PageSummary,
  CreatePageInput,
  UpdatePageInput,
  MediaItem,
  AnalyticsSummary,
  Product,
  Booking,
  OptimoCMSError,
  PaginatedResponse,
} from '@optimocms/sdk';

Try it — curl equivalent:

# The SDK hides these details, but this is what happens under the hood
curl https://api.optimocms.com/v1/sites \
  -H "X-Api-Key: optimo_live_abc123def456"

Try it — MCP equivalent:

Use the list_sites tool.

Next steps

Error handling — Typed errors, retry strategy and 429 handling
Pagination — Async iterators and cursor-based pagination
Authentication — Scopes and rate limits
API Reference — All endpoints

TypeScript SDK — Installation