Contentful Management JS Client

Every call to the Content Management API (CMA) follows a four-stage pipeline:

1. createClient(): Builds the user-agent, initializes the adapter, and selects the client surface (Plain or Legacy).
2. Client Surface: The Plain or Legacy client produces a MakeRequestOptions object containing { entityType, action, params, payload, headers, userAgent } via a makeRequest(opts) closure.
3. Adapter.makeRequest: The adapter (typically RestAdapter) uses an axios instance to handle the request, including built-in rate limiting and retries.
4. Endpoint Lookup: The adapter resolves the entityType and action against a registry to determine the specific HTTPS endpoint and method (GET, POST, etc.) to call api.contentful.com.

The library now targets ECMAScript 2021. Babel transpilation for older JavaScript versions has been removed. Modern features like optional chaining (?.), nullish coalescing (??), and Promise.any() are used directly.

Affected environments:

• Internet Explorer (all versions)
• Chrome < 85
• Firefox < 79
• Safari < 14
• Edge < 85
• Node.js < 14.17

If you must support these environments, you will need to add an additional transpilation step (e.g., using Babel) to your build process.

The following APIs are currently experimental and may change without notice:

• AI Agents: getAgent, getAgents, getAgentRun, getAgentRuns, generateWithAgent, resumeAgentRun.
• Experiences: componentType, template, fragment, experience, dataAssembly, designToken.

The SDK allows you to replace the default RestAdapter with a custom implementation of the Adapter interface. This is useful for:

• Contentful Apps: Passing sdk.cmaAdapter as the apiAdapter to proxy requests through the host web app.
• Unit Testing: Providing a mock adapter to avoid network calls.

To use a custom adapter, pass an object containing apiAdapter in the createClient options. This is mutually exclusive with providing RestAdapterParams (like accessToken).

// Example: Using a custom adapter (e.g., in a Contentful App)
const client = createClient({
  apiAdapter: sdk.cmaAdapter
});

In v12, createClient returns the plain client by default. The legacy nested client is deprecated and will be removed in the next major version.

Migration:

• Recommended: Migrate your code to use the plain client API.
• To keep using the legacy client: Explicitly pass { type: 'legacy' } in the options.

// Before - implicitly used nested client
const client = createClient({ accessToken: 'token' })

// After - explicitly request legacy nested client
const client = createClient({ accessToken: 'token' }, { type: 'legacy' })

You can install the library via npm or yarn for Node.js environments, or include it via a script tag for browser usage.

Node.js

Use npm:

npm install contentful-management

Use yarn:

yarn add contentful-management

Browser

Include the library via jsDelivr using a script tag. It is recommended to specify a version to ensure stability.

<script src="https://cdn.jsdelivr.net/npm/contentful-management@12"></script>

When using the script tag, the library is accessible via the global contentfulManagement variable.

When building apps for the Contentful App Framework using @contentful/app-sdk, you should use the provided apiAdapter to make requests. This allows your app to access space-environment scoped entities securely without exposing a management token.

const contentfulApp = require('@contentful/app-sdk')
const contentful = require('contentful-management')

contentfulApp.init((sdk) => {
  const cma = contentful.createClient(
    { apiAdapter: sdk.cmaAdapter },
    {
      defaults: {
        environmentId: sdk.ids.environmentAlias ?? sdk.ids.environment,
        spaceId: sdk.ids.space,
      },
    },
  )

  // ...rest of initialization code
})

Note: Requests issued via the sdk.cmaAdapter count towards the same rate-limiting quota as other APIs exposed by the App SDK.

If you are upgrading to v12 or later and your code relies on the nested/chained client pattern (e.g., client.getSpace(id).getEnvironment(id)), your code will break because createClient() now defaults to the Plain Client.

To restore the old behavior temporarily, you must explicitly pass { type: 'legacy' } as the second argument to createClient.

Warning: The legacy client is scheduled for removal in the next major version. You should plan to migrate your logic to the Plain Client's flat namespace as soon as possible.

// BREAKING CHANGE: This used to return a nested client, now it returns a plain client
// const client = createClient({ accessToken }); 

// FIX for existing code: 
const client = createClient({ accessToken }, { type: 'legacy' });

To use features that are still in development and may be unstable, you can install the canary channel via npm:

npm install contentful-management@canary

The exports field in package.json now restricts access to internal modules. If you are using contentful-management/types and encounter errors, you have two options:

Option 1: Update tsconfig.json Set moduleResolution to a modern value like node16, nodenext, or bundler.

{
  "compilerOptions": {
    "moduleResolution": "node16"
  }
}

Option 2: Import from the main package Import types directly from contentful-management instead of the /types subpath.

// Instead of
import type { Space } from 'contentful-management/types'

// Use
import type { Space } from 'contentful-management'