Content Management API

Using the JavaScript client

If you're familiar with Javascript/TypeScript, you can make use of our official client to perform requests to the Content Management API.

It offers a number of benefits over making raw requests yourself:

The package is written in TypeScript, so every method is fully typed and offers editor auto-completion and type checks;
Tedious tasks like API rate limits retry, asyncronous jobs management, pagination and creation of new assets are either automatically managed for you, or greatly simplified with simple methods that hide the inner complexities.

How to install the client

DatoCMS provides three JavaScript client packages, each optimized for different runtime environments:

npm install @datocms/cma-client           # Generic/agnostic (recommended for most cases)
npm install @datocms/cma-client-node      # Node.js with filesystem access
npm install @datocms/cma-client-browser   # Browser-optimized

@datocms/cma-client (generic/agnostic) — The safest and most portable choice. Use it for:

Edge functions (Cloudflare Workers, Vercel Edge Functions, etc.)
Serverless functions (AWS Lambda, Netlify Functions, etc.)
Any environment where maximum compatibility is needed

@datocms/cma-client-node — Use this if you're in a Node.js environment to get the best experience. It provides specialized helper methods for uploading files: createFromLocalFile() for local filesystem files and createFromUrl() for remote URLs. This gives you the most convenient API when working with Node.js and filesystem access.

@datocms/cma-client-browser — Use this if you're in a browser environment to get the best experience. It provides the createFromFileOrBlob() helper method for handling File and Blob objects from <input type="file" /> elements, giving you the most convenient API when working with user file uploads.

If you don't need these specialized upload helpers, the generic @datocms/cma-client package is the best choice — it works in more environments and avoids potential compatibility issues.

Initializing the client

You can use the buildClient function to initialize a new client.

import { buildClient } from '@datocms/cma-client-node';

const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });

Specifying a sandbox environment

By default, every API request you perform will point to the current primary environment, but if you want to make changes to a specific sandbox environment, you can pass it in the initialization options:

import { buildClient } from '@datocms/cma-client-node';

const client = buildClient({
  apiToken: process.env.DATOCMS_API_TOKEN,
  environment: 'my-sandbox-environment',
});

Logging request/responses

The client can output logs of the API request and responses it performs to help you debug issues with your code. You can choose different level of logging, depending on how much information you need:

import { buildClient, LogLevel } from '@datocms/cma-client-node';

const client = buildClient({
  apiToken: process.env.DATOCMS_API_TOKEN,
  logLevel: LogLevel.BASIC,
});

The different levels of logging available are:

LogLevel.NONE (the default level): No output is generated;
LogLevel.BASIC: Logs HTTP requests (method, URL) and responses (status);
LogLevel.BODY: Logs HTTP requests (method, URL, body) and responses (status, body);
LogLevel.BODY_AND_HEADERS: Logs HTTP requests (method, URL, headers, body) and responses (status, headers, body).

Entity collections and pagination

Take a look at the Pagination section to understand how pagination works, and which methods the JavaScript client provides to make your task easier.

Raw vs Simplified endpoint methods

The client is organized by type of resource. For every resource, it offers a number of async methods to perform a CRUD request to a specific endpoint of the API:

// Example: Item Type (Model)

await client.itemType.rawList(...);
await client.itemType.rawFind(...);
await client.itemType.rawCreate(...);
await client.itemType.rawUpdate(...);
await client.itemType.rawDestroy(...);

"Why the raw prefix on all the methods?" you might ask. Well, let's take a closer look at one specific method call — in this case, the update of an existing model.

As already covered in previous sections, the API follows the JSON:API convention, which requires a specific format for the payloads. Every request/response has a data attribute, which contains a number of Resource Objects, which in turn contain different of top-level members (id, type, attributes, relationships, meta, etc), each with their own semantic:

1
const response = await client.itemTypes.rawUpdate('34532432', {
2
  data: {
3
    id: '34532432',
4
    type: 'item_type',
5
    attributes: {
6
      name: 'Article',
7
      api_key: 'article',
8
    },
9
    relationships: {
10
      title_field: { data: { id: '451235', type: 'field' } },
11
    },
12
  }
13
});
14

15
console.log(`Created model ${response.data.attributes.name}!`);

As you can see from the example above, it can become very verbose to write even simple code using this format! That's why the client also offers a "simplified" method for every endpoint — without the raw prefix — which greatly reduces the amount of boilerplate code required:

const itemType = await client.itemTypes.update('34532432', {
  name: 'Article',
  api_key: 'article',
  title_field: { id: '451235', type: 'field' },
});

console.log(`Created model ${itemType.name}!`);

So the complete set of methods available for the Model resource is:

1
// Example: Item Type (Model)
2

3
await client.itemType.list(...);
4
await client.itemType.rawList(...);
5

6
await client.itemType.find(...);
7
await client.itemType.rawFind(...);
8

9
await client.itemType.create(...);
10
await client.itemType.rawCreate(...);
11

12
await client.itemType.update(...);
13
await client.itemType.rawUpdate(...);
14

15
await client.itemType.destroy(...);
16
await client.itemType.rawDestroy(...);

In the next sections, you'll find a real-world usage example of the client for every endpoint offered by the API.

Error management

In case an API call fails with HTTP status code outside of the 2xx range, an ApiError exception will be raised by the client, containing all the details of the request/response.

1
import { ApiError } from '@datocms/cma-client-node';
2

3
try {
4
  await client.itemType.create({
5
    name: 'Article',
6
    api_key: 'article',
7
  });
8
} catch(e) {
9
  if (e instanceof ApiError) {
10
    // Information about the failed request
11
    console.log(e.request.url);
12
    console.log(e.request.method);
13
    console.log(e.request.headers);
14
    console.log(e.request.body);
15

16
    // Information about the response
17
    console.log(e.response.status);
18
    console.log(e.response.statusText);
19
    console.log(e.response.headers);
20
    console.log(e.response.body);
21
  } else {
22
    throw e;
23
  }
24
}

The error object also includes a .findError() method that you can use to check if the response includes a particular error code:

// finds in the array of api_error entities an error with code 'INVALID_FIELD',
// that in its details has the key 'field' set to 'api_key':
const errorEntity = e.findError('INVALID_FIELD', { field: 'api_key' });

`SchemaRepository` utility for efficient schema access

When working with complex operations that require frequent access to schema information (models, fields, fieldsets, and plugins), the SchemaRepository utility provides an efficient caching layer to avoid redundant API calls.

1
class SchemaRepository {
2
  constructor(client: GenericClient)
3

4
  // Item Type methods
5
  async getAllItemTypes(): Promise<ItemType[]>
6
  async getAllModels(): Promise<ItemType[]>
7
  async getAllBlockModels(): Promise<ItemType[]>
8
  async getItemTypeByApiKey(apiKey: string): Promise<ItemType>
9
  async getItemTypeById(id: string): Promise<ItemType>
10

11
  // Field methods
12
  async getItemTypeFields(itemType: ItemType): Promise<Field[]>
13
  async getItemTypeFieldsets(itemType: ItemType): Promise<Fieldset[]>
14

15
  // Plugin methods
16
  async getAllPlugins(): Promise<Plugin[]>
17
  async getPluginById(id: string): Promise<Plugin>
18
  async getPluginByPackageName(packageName: string): Promise<Plugin>
19

20
  // Raw variants (return full JSON:API response format)
21
  async getAllRawItemTypes(): Promise<RawItemType[]>
22
  async getRawItemTypeByApiKey(apiKey: string): Promise<RawItemType>
23
  // ... and more raw variants
24
}

Purpose

SchemaRepository is designed to solve performance problems when repeatedly fetching the same schema information during operations that traverse nested blocks, structured text, or modular content. It acts as an in-memory cache for schema entities.

Without SchemaRepository, a script processing fields containing nested blocks might make the same client.itemTypes.list() or client.fields.list() calls dozens of times: SchemaRepository ensures each unique schema request is made only once.

1
import { SchemaRepository, mapBlocksInNonLocalizedFieldValue } from '@datocms/cma-client';
2

3
const schemaRepository = new SchemaRepository(client);
4

5
// These calls will hit the API and cache the results
6
const models = await schemaRepository.getAllModels();
7
const blogPost = await schemaRepository.getItemTypeByApiKey('blog_post');
8

9
// These subsequent calls will return cached results (no API calls)
10
const sameModels = await schemaRepository.getAllModels();
11
const sameBlogPost = await schemaRepository.getItemTypeByApiKey('blog_post');
12

13
// Pass the repository to utilities that need schema information
14
await mapBlocksInNonLocalizedFieldValue(record.content, 'rich_text', schemaRepository, (block, path) => {
15
  // The utility will use the cached schema data internally
16
});

What's it for

Caching schema entities: Automatically caches item types, fields, fieldsets, and plugins after the first API request
Complex traversal operations: Essential when using utilities like mapBlocksInNonLocalizedFieldValue() that need to repeatedly lookup block models and fields
Bulk operations: Ideal for scripts that process multiple records of different types
Read-heavy workflows: Perfect for scenarios where you need to repeatedly access the same schema information

When NOT to use it

Schema modification: Do NOT use if your script modifies models, fields, fieldsets, or plugins, as the cache will become stale!
Long-running applications: The cache has no expiration mechanism!
Concurrent schema changes: No protection against cache inconsistency!

Pro tip: Best practices

Create one instance per script execution, not per operation, and make sure to use SchemaRepository consistently throughout your script for maximum cache efficiency!

Ponyfilling `fetch()`

If your Javascript environment does not provide the Fetch API interface — for example, if you are using a version of Node lower than 18 — you will need to specify a ponyfill during client configuration:

import { buildClient } from '@datocms/cma-client-node';
import { fetch } from '@whatwg-node/fetch';

const client = buildClient({ apiToken: '<YOUR_TOKEN>', fetchFn: fetch });