Guides · Reference · Contributing

The Contentful Optimization API Client provides low-level transport for the Experience API and Insights API. Application-facing SDKs compose this package with event builders, state management, queueing, and runtime-specific defaults.

We recommend starting applications with Web, React Web, Node, or React Native SDKs. Use this package directly when building or maintaining SDK layers, tests, tooling, or first-party integrations that need raw API access.

• Getting started
• When to use this package
• Common configuration
• API surface
  • Experience API
  • Insights API
  • Fetch helpers
• Related

Getting started

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

pnpm install @contentful/optimization-api-client

Import and initialize the unified API client; both CJS and ESM module systems are supported, ESM preferred:

import { ApiClient } from '@contentful/optimization-api-client'

const client = new ApiClient({
  clientId: 'your-client-id',
  environment: 'main',
})

When to use this package

Use @contentful/optimization-api-client when you need direct low-level access to the Experience API or Insights API transport surface. Use an application-facing SDK when you need optimization state, consent handling, event builders, entry resolution, tracking, or platform defaults.

Common configuration

| Option | Required? | Default | Description | | -------------- | --------- | ---------------------------- | ----------------------------------------------------------- | | clientId | Yes | N/A | Shared API key for Experience API and Insights API requests | | environment | No | 'main' | Contentful environment identifier | | experience | No | See Experience options below | Experience API endpoint and default request options | | insights | No | See Insights options below | Insights API endpoint options | | fetchOptions | No | SDK defaults | Fetch timeout and retry behavior |

Common Experience API options:

| Option | Required? | Default | Description | | ----------------- | --------- | ------------------------------------- | ----------------------------------------------- | | baseUrl | No | 'https://experience.ninetailed.co/' | Base URL for the Experience API | | enabledFeatures | No | ['ip-enrichment', 'location'] | Experience API features for mutation requests | | ip | No | undefined | IP address override for Experience API analysis | | locale | No | API default | Locale query parameter for localized responses | | plainText | No | Endpoint-specific | Sends single-profile mutation endpoints as text | | preflight | No | false | Aggregates a profile state without storing it |

Experience mutation request options except baseUrl can also be provided per mutation request. getProfile is a read request and only uses locale from per-call options; mutation-only options such as enabledFeatures, ip, plainText, and preflight do not apply. Single-profile mutation requests default to plainText: true and send text/plain unless overridden. Batch profile updates with upsertManyProfiles are the JSON-default exception and use plainText: false by default. locale is sent as the Experience API locale query parameter and can localize profile fields such as location.city and location.country. Higher-level SDK merge-tag helpers resolve against the profile values returned by the Experience API, so applications that render localized Contentful entries commonly pass the same locale used for the CDA entry fetch. Pass a valid locale tag; invalid locale syntax can fail Experience API request validation. See Locale handling in the Optimization SDK Suite for how this request locale relates to Contentful and SDK-resolved locales.

Common Insights API options:

| Option | Required? | Default | Description | | --------- | --------- | ------------------------------------------ | ----------------------------- | | baseUrl | No | 'https://ingest.insights.ninetailed.co/' | Base URL for the Insights API |

Common fetchOptions are fetchMethod, requestTimeout, retries, intervalTimeout, onFailedAttempt, and onRequestTimeout. Default retries intentionally apply only to HTTP 503 responses.

For every option, callback payload, request type, and response type, use the generated API Client reference.

API surface

Experience API

Experience API methods are scoped to client.experience and return profile and optimization data:

const { profile, selectedOptimizations, changes } = await client.experience.upsertProfile(
  {
    profileId: 'f0837d7dc6344c36a3a0a06c4cde754b',
    events: [pageEvent],
  },
  { locale: 'de-DE' },
)

Common methods include getProfile, createProfile, updateProfile, upsertProfile, and upsertManyProfiles.

Insights API

Insights API methods are scoped to client.insights and send analytics event batches:

await client.insights.sendBatchEvents([
  {
    profile,
    events: [viewEvent],
  },
])

Insights endpoints do not return response data. For last-chance browser lifecycle delivery, pass a per-call beacon sender that receives the request URL and already serialized body.

Fetch helpers

This package also exports fetch helper functions used by SDK layers:

| Helper | Purpose | | ---------------------------- | ------------------------------------------------------- | | createProtectedFetchMethod | Adds timeout and retry protection around a fetch method | | createRetryFetchMethod | Applies retry policy to retryable responses | | createTimeoutFetchMethod | Aborts requests after the configured timeout |

Use generated reference docs for helper signatures and callback payloads.

Related

• API Client generated reference - exported API reference
• API Schemas - runtime validation schemas and inferred API types
• Optimization Core SDK - platform-agnostic SDK layer that composes this client
• Choosing the right SDK - package selection guidance for application integrations