Contentful Personalization & Analytics

API Schema Library

The Contentful Optimization API Schema Library provides Zod Mini schemas, inferred TypeScript types, and small runtime helpers for Contentful CDA, Experience API, and Insights API payloads. SDK layers use this package to validate API contracts and normalize optimization data.

Table of Contents

• Getting started
• When to use this package
• Package surface
  • Contentful CDA helpers
  • Experience API schemas
  • Insights API schemas
• Related

Getting started

Install using an NPM-compatible package manager, pnpm for example:

pnpm install @contentful/optimization-api-schemas
Copy

Import schemas or helpers from the package:

import { isOptimizedEntry, normalizeOptimizationConfig } from '@contentful/optimization-api-schemas'
Copy

Consult Zod's documentation for more information on working with Zod Mini schemas.

When to use this package

Use @contentful/optimization-api-schemas when you need shared runtime validation schemas or inferred TypeScript types for Contentful CDA, Experience API, and Insights API payloads. Most application integrations must use an environment SDK instead of importing schemas directly.

Package surface

Contentful CDA helpers

These helpers identify and normalize Contentful entries for optimization:

Export	Purpose
CtflEntry	Generic Contentful entry schema
OptimizedEntry	Entry schema with associated optimization entries
OptimizationEntry	Optimization entry schema referenced by fields.nt_experiences
OptimizationConfig	Optimization configuration schema from fields.nt_config
isEntry	Type guard for Contentful Entry values
isOptimizedEntry	Type guard for optimized entries
isOptimizationEntry	Type guard for optimization entries
normalizeOptimizationConfig	Fills omitted optimization config fields with SDK-safe defaults

Experience API schemas

Experience API schemas validate profile evaluation request and response payloads:

Export	Purpose
ExperienceRequestData	Request payload for a single Experience API call
BatchExperienceRequestData	Request payload for batch Experience API calls
ExperienceEvent	Union of supported Experience API event schemas
BatchExperienceEvent	Batch event schema with required anonymousId per event
ExperienceResponse	Full Experience API response envelope
BatchExperienceResponse	Batch Experience API response envelope
Change	Supported change union, including Custom Flag data
SelectedOptimization	Selected optimization outcome for a profile
Profile	User profile returned by the Experience API

Insights API schemas

Insights API schemas validate event ingestion payloads:

Export	Purpose
InsightsEvent	Union of supported Insights API event schemas
BatchInsightsEvent	Batched Insights API payload with profile and event entries
ClickEvent	component_click event schema
HoverEvent	component_hover event schema
ViewEvent	component view event schema

For every schema, inferred type, and helper signature, use the generated API Schemas reference.

Related

• API Schemas generated reference - exported schema and type reference
• API Client - low-level Experience API and Insights API transport
• Optimization Core SDK - platform-agnostic SDK layer that consumes these schemas
• Choosing the right SDK - package selection guidance for application integrations