### Public Plugin Installation Response

Source: https://www.datocms.com/docs/content-management-api/resources/plugin/create

This is an example of the JSON response received after successfully installing a public plugin from NPM.

```json
const result = {
  type: "plugin",
  id: "124",
  name: "5 stars",
  description: "A better rating experience!",
  package_name: "datocms-plugin-star-rating-editor",
  package_version: "0.0.4",
  url: "https://cdn.rawgit.com/datocms/extensions/master/samples/five-stars/extension.js",
  permissions: ["currentUserAccessToken"],
  parameters: {},
};

```

--------------------------------

### Role Creation Output Example

Source: https://www.datocms.com/docs/content-management-api/resources/role/create

This is an example of the output received after successfully creating a role with specific permissions and inheritance.

```json
Created role: 443077 — Editor (no delete)
Effective record permissions (final_permissions): [
  {
    "environment": "main",
    "item_type": null,
    "workflow": null,
    "on_stage": null,
    "to_stage": null,
    "action": "all",
    "on_creator": "anyone",
    "localization_scope": "all",
    "locale": null
  }
]
Effective negative entries: [
  {
    "environment": "main",
    "item_type": null,
    "workflow": null,
    "on_stage": null,
    "to_stage": null,
    "action": "delete",
    "on_creator": "anyone",
    "localization_scope": null,
    "locale": null
  }
]

```

--------------------------------

### Returned Output Example

Source: https://www.datocms.com/docs/content-management-api/resources/site/activate_improved_timezone_management

This is an example of the JSON response you will receive after successfully activating improved timezone management.

```json
{
  id: "155",
  domain: "admin.my-awesome-website.com",
  favicon: "123",
  global_seo: {},
  google_maps_api_token: "xxxxxxxxxxxxx",
  imgix_host: "www.datocms-assets.com",
  internal_domain: "my-website.admin.datocms.com",
  last_data_change_at: "2017-03-30T09:29:14.872Z",
  locales: ["en"],
  name: "My Awesome Website",
  no_index: true,
  require_2fa: false,
  theme: { type: "monochromatic", hue: 16, logo: "123" },
  timezone: "Europe/London",
  ip_tracking_enabled: true,
  force_use_of_sandbox_environments: true,
  assets_cdn_default_settings: { image: {}, video: {} },
  meta: {
    created_at: "2020-04-21T07:57:11.124Z",
    improved_timezone_management: true,
    improved_hex_management: true,
    improved_gql_multilocale_fields: true,
    improved_gql_visibility_control: true,
    improved_boolean_fields: true,
    draft_mode_default: true,
    improved_validation_at_publishing: true,
    improved_exposure_of_inline_blocks_in_cda: true,
    improved_items_listing: true,
    milliseconds_in_datetime: true,
    non_localized_focal_points: true,
  },
  item_types: [{ type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" }],
  owner: { type: "account", id: "312" }
}
```

--------------------------------

### Install Public Plugin from NPM

Source: https://www.datocms.com/docs/content-management-api/resources/plugin/create

Demonstrates how to install a public plugin from NPM. This is the standard method for adding community or pre-built plugins to your project.

```javascript
import { createPlugin } from "@datocms/content-management-plugin-sdk";

createPlugin({
  // ... plugin configuration
});

```

--------------------------------

### Returned Output Example

Source: https://www.datocms.com/docs/content-management-api/resources/site/activate_improved_validation_at_publishing

This is an example of the JSON output returned after successfully activating the improved validation at publishing option.

```json
{
  "id": "155",
  "domain": "admin.my-awesome-website.com",
  "favicon": "123",
  "global_seo": {},
  "google_maps_api_token": "xxxxxxxxxxxxx",
  "imgix_host": "www.datocms-assets.com",
  "internal_domain": "my-website.admin.datocms.com",
  "last_data_change_at": "2017-03-30T09:29:14.872Z",
  "locales": ["en"],
  "name": "My Awesome Website",
  "no_index": true,
  "require_2fa": false,
  "theme": { "type": "monochromatic", "hue": 16, "logo": "123" },
  "timezone": "Europe/London",
  "ip_tracking_enabled": true,
  "force_use_of_sandbox_environments": true,
  "assets_cdn_default_settings": { "image": {}, "video": {} },
  "meta": {
    "created_at": "2020-04-21T07:57:11.124Z",
    "improved_timezone_management": true,
    "improved_hex_management": true,
    "improved_gql_multilocale_fields": true,
    "improved_gql_visibility_control": true,
    "improved_boolean_fields": true,
    "draft_mode_default": true,
    "improved_validation_at_publishing": true,
    "improved_exposure_of_inline_blocks_in_cda": true,
    "improved_items_listing": true,
    "milliseconds_in_datetime": true,
    "non_localized_focal_points": true
  },
  "item_types": [{ "type": "item_type", "id": "DxMaW10UQiCmZcuuA-IkkA" }],
  "owner": { "type": "account", "id": "312" }
}
```

--------------------------------

### Plugin Resource Object Example

Source: https://www.datocms.com/docs/content-management-api/resources/plugin/self

This is an example of the JSON structure returned when successfully retrieving a plugin resource.

```json
{
  "id": "RMAMRffBRlmBuDlQsIWZ0g",
  "name": "5 stars",
  "description": "A better rating experience!",
  "url": "https://cdn.rawgit.com/datocms/extensions/master/samples/five-stars/extension.ts",
  "parameters": { "devMode": true },
  "package_name": "datocms-plugin-star-rating-editor",
  "package_version": "0.0.4",
  "permissions": ["currentUserAccessToken"],
  "meta": { "version": "2" }
}

```

--------------------------------

### Example Site Invitation Object

Source: https://www.datocms.com/docs/content-management-api/resources/site-invitation/instances

This is an example of the structure of a single site invitation object returned by the API.

```json
{
  "id": "312",
  "email": "mark.smith@example.com",
  "expired": "mark.smith@example.com",
  "role": { "type": "role", "id": "34" }
}

```

--------------------------------

### Example User Resource

Source: https://www.datocms.com/docs/content-management-api/resources/user/instances

This is an example of the structure of a user resource object returned by the API.

```json
{
  id: "312",
  email: "mark.smith@example.com",
  is_2fa_active: true,
  full_name: "Mark Smith",
  is_active: true,
  role: { type: "role", id: "34" },
}
```

--------------------------------

### Example Returned Output

Source: https://www.datocms.com/docs/content-management-api/resources/item/current_vs_published_state

This is an example of the JSON response you can expect when querying the current vs. published state of an item. It details locale differences and field changes.

```json
{
  id: "EnO-NF5wRy6K-cxGt1doqg",
  current_version_locales: [""],
  published_version_locales: [""],
  changed_locales: [""],
  added_locales: [""],
  removed_locales: [""],
  non_localized_fields_changed: true,
  current_version_invalid_locales: [""],
  current_version_non_localized_fields_invalid: true,
  scheduled_publication: { type: "scheduled_publication", id: "34" },
  scheduled_unpublishing: { type: "scheduled_unpublishing", id: "34" },
  published_version: { type: "item_version", id: "59JSonvYTCOUDz_b7_6hvA" }
}
```

--------------------------------

### Create Item Example

Source: https://www.datocms.com/docs/content-management-api/resources/item/create

This example demonstrates how to create a new 'Product' item with various field types. It shows the structure for simple fields like text and numbers, as well as complex types like geo-location, color, and JSON.

```APIDOC
## POST /items

### Description
Creates a new item of a specified item type.

### Method
POST

### Endpoint
/items

### Request Body
- **item_type** (string) - Required - The ID of the item type for the new item.
- **name** (string) - Required - The name of the item.
- **category** (string) - Required - The category of the item.
- **description** (text) - Optional - A detailed description of the item.
- **price** (integer) - Required - The price of the item.
- **weight** (float) - Optional - The weight of the item.
- **release_date** (date_time) - Optional - The release date of the item in ISO 8601 format.
- **in_stock** (boolean) - Optional - Indicates if the item is currently in stock.
- **warehouse_location** (lat_lon) - Optional - The geographical location of the item in the warehouse.
  - **latitude** (float) - Required - The latitude coordinate.
  - **longitude** (float) - Required - The longitude coordinate.
- **brand_color** (color) - Optional - The brand color associated with the item.
  - **red** (integer) - Required - The red component (0-255).
  - **green** (integer) - Required - The green component (0-255).
  - **blue** (integer) - Required - The blue component (0-255).
  - **alpha** (integer) - Optional - The alpha component (0-255).
- **specifications** (json) - Optional - A JSON-serialized string of the item's specifications.

### Request Example
```json
{
  "item_type": "YOUR_ITEM_TYPE_ID",
  "name": "Premium Wireless Headphones",
  "category": "Electronics",
  "description": "High-quality noise-cancelling wireless headphones. Perfect for music and calls.",
  "price": 299,
  "weight": 0.25,
  "release_date": "2024-03-15T10:30:00",
  "in_stock": true,
  "warehouse_location": {
    "latitude": 45.0703393,
    "longitude": 7.686864
  },
  "brand_color": {
    "red": 239,
    "green": 208,
    "blue": 156,
    "alpha": 255
  },
  "specifications": "{\"bluetooth\": \"5.0\", \"battery_life\": \"30h\", \"warranty\": \"2y\"}"
}
```

### Response
#### Success Response (200)
Returns the created item object, including its ID and all its fields.

#### Response Example
```json
{
  "id": "NZwcu3wYSgWeAbqVCJVToQ",
  "item_type": "UZyfjdBES8y2W2ruMEHSoA",
  "name": "Premium Wireless Headphones",
  "category": "Electronics",
  "description": "High-quality noise-cancelling wireless headphones. Perfect for music and calls.",
  "price": 299,
  "weight": 0.25,
  "release_date": "2024-03-15T10:30:00+00:00",
  "in_stock": true,
  "warehouse_location": {
    "latitude": 45.0703393,
    "longitude": 7.686864
  },
  "brand_color": {
    "red": 239,
    "green": 208,
    "blue": 156,
    "alpha": 255
  },
  "specifications": {
    "bluetooth": "5.0",
    "battery_life": "30h",
    "warranty": "2y"
  }
}
```
```

--------------------------------

### Example Published Item Output

Source: https://www.datocms.com/docs/content-management-api/resources/item/publish

This is an example of the JSON output returned after successfully publishing an item. It includes metadata, content, and item type information.

```json
{
  "id": "hWl-mnkWRYmMCSTq4z_piQ",
  "title": "My first blog post!",
  "content": "Lorem ipsum dolor sit amet...",
  "category": "24",
  "image": {
    "alt": "Alt text",
    "title": "Image title",
    "custom_data": {},
    "focal_point": null,
    "upload_id": "20042921",
  },
  "meta": {
    "created_at": "2020-04-21T07:57:11.124Z",
    "updated_at": "2020-04-21T07:57:11.124Z",
    "published_at": "2020-04-21T07:57:11.124Z",
    "first_published_at": "2020-04-21T07:57:11.124Z",
    "publication_scheduled_at": "2020-04-21T07:57:11.124Z",
    "unpublishing_scheduled_at": "2020-04-21T07:57:11.124Z",
    "status": "published",
    "is_current_version_valid": true,
    "is_published_version_valid": true,
    "current_version": "4234",
    "stage": null,
    "has_children": true,
  },
  "item_type": { "type": "item_type", "id": "DxMaW10UQiCmZcuuA-IkkA" },
}
```

--------------------------------

### Bulk Block Operations Example

Source: https://www.datocms.com/docs/content-management-api/resources/item/update

This example demonstrates the output of bulk operations, showing the state of items before and after processing. It illustrates changes in specific fields like 'style' within nested blocks.

```text
1
📋 Processing records of model: Landing Page (landing_page)
2


3
--- Processing IwcHsSQ5SSa2LYzpk_Ddjw ---
4
BEFORE:
5
└ Item "IwcHsSQ5SSa2LYzpk_Ddjw" (item_type: "KUz2pYAvQvOWqv3dVwVw3w")
6
  └ hero_cta
7
    └ Item "fnclskI4RG25uLQC92XE5g" (item_type: "DC2XVF6BTjGBgQaoaih6Og")
8
      ├ title: "Transform Your Business"
9
      ├ description: "Take the next step forward"
10
      ├ button_text: "Get started"
11
      ├ button_url: "/start"
12
      └ style: "muted"
13


14
AFTER:
15
└ Item "IwcHsSQ5SSa2LYzpk_Ddjw" (item_type: "KUz2pYAvQvOWqv3dVwVw3w")
16
  └ hero_cta
17
    └ Item "fnclskI4RG25uLQC92XE5g" (item_type: "DC2XVF6BTjGBgQaoaih6Og")
18
      ├ title: "Transform Your Business"
19
      ├ description: "Take the next step forward"
20
      ├ button_text: "Get started"
21
      ├ button_url: "/start"
22
      └ style: "primary"
23


24

25
📋 Processing records of model: Article (article)
26

27
--- Processing JPplplyPTMKpCbB-wipxeA ---
28
BEFORE:
29
└ Item "JPplplyPTMKpCbB-wipxeA" (item_type: "ONxSjA4WTWaoNJY2zokUoQ")
30
  ├ title
31
  │ ├ en: "Sample Article"
32
  │ └ it: "Articolo di Esempio"
33
  ├ content
34
  │ ├ en
35
  │ │ ├ paragraph
36
  │ │ │ └ span "Introduction text"
37
  │ │ ├ block
38
  │ │ │ └ Item "BOps1UFgSU-CSm-fRjoqCA" (item_type: "DC2XVF6BTjGBgQaoaih6Og")
39
  │ │ │   ├ title: "Join Our Platform"
40
  │ │ │   ├ description: "Start your journey today"
41
  │ │ │   ├ button_text: "Sign up"
42
  │ │ │   ├ button_url: "/signup"
43
  │ │ │   └ style: "muted"
44
  │ │ └ paragraph
45
  │ │   └ span "Conclusion text"
46
  │ └ it
47
  │   ├ paragraph
48
  │   │ └ span "Testo introduttivo"
49
  │   └ block
50
  │     └ Item "SSVQgIbZS_uoPQWg-qYzWg" (item_type: "DC2XVF6BTjGBgQaoaih6Og")
51
  │       ├ title: "Scopri di Più"
52
  │       ├ description: "Leggi la nostra guida"
53
  │       ├ button_text: "Learn more"
54
  │       ├ button_url: "/guide"
55
  │       └ style: "primary"
56
  └ sidebar
57
    └ [0] Item "f86JBAwxTsasu7J3XxXqJg" (item_type: "DC2XVF6BTjGBgQaoaih6Og")
58
      ├ title: "Special Offer"
59
      ├ description: "Limited time promotion"
60
      ├ button_text: "Buy now"
61
      ├ button_url: "/buy"
62
      └ style: "muted"
63


64
AFTER:
65
└ Item "JPplplyPTMKpCbB-wipxeA" (item_type: "ONxSjA4WTWaoNJY2zokUoQ")
66
  ├ title
67
  │ ├ en: "Sample Article"
68
  │ └ it: "Articolo di Esempio"
69
  ├ content
70
  │ ├ en
71
  │ │ ├ paragraph
72
  │ │ │ └ span "Introduction text"
73
  │ │ ├ block
74
  │ │ │ └ Item "BOps1UFgSU-CSm-fRjoqCA" (item_type: "DC2XVF6BTjGBgQaoaih6Og")
75
  │ │ │   ├ title: "Join Our Platform"
76
  │ │ │   ├ description: "Start your journey today"
77
  │ │ │   ├ button_text: "Sign up"
78
  │ │ │   ├ button_url: "/signup"
79
  │ │ │   └ style: "primary"
80
  │ │ └ paragraph
81
  │ │   └ span "Conclusion text"
82
  │ └ it
83
  │   ├ paragraph
84
  │   │ └ span "Testo introduttivo"
85
  │   └ block
86
  │     └ Item "SSVQgIbZS_uoPQWg-qYzWg" (item_type: "DC2XVF6BTjGBgQaoaih6Og")
87
  │       ├ title: "Scopri di Più"
88
  │       ├ description: "Leggi la nostra guida"
89
  │       ├ button_text: "Learn more"
90
  │       ├ button_url: "/guide"
91
  │       └ style: "muted"
92
  └ sidebar
93
    └ [0] Item "f86JBAwxTsasu7J3XxXqJg" (item_type: "DC2XVF6BTjGBgQaoaih6Og")
94
      ├ title: "Special Offer"
95
      ├ description: "Limited time promotion"
96
      ├ button_text: "Buy now"
97
      ├ button_url: "/buy"
98
      └ style: "primary"

```

--------------------------------

### Example Menu Item Output

Source: https://www.datocms.com/docs/content-management-api/resources/menu-item/instances

This is an example of the JSON structure returned when listing menu items. It includes details like ID, label, position, and associated item types.

```json
{
  "id": "uinr2zfqQLeCo_1O0-ao-Q",
  "label": "Posts",
  "position": 1,
  "external_url": "",
  "open_in_new_tab": true,
  "item_type": { "type": "item_type", "id": "DxMaW10UQiCmZcuuA-IkkA" },
  "item_type_filter": { "type": "item_type_filter", "id": "FF-P5of6Qp-DD2w0xoaa6Q" },
  "parent": null,
  "children": [{ "type": "menu_item", "id": "uinr2zfqQLeCo_1O0-ao-Q" }]
}

```

--------------------------------

### Returned Output Example

Source: https://www.datocms.com/docs/content-management-api/resources/item-type/reorder_fields_and_fieldsets

This is an example of the JSON output returned after successfully reordering fields and fieldsets. It shows the updated attributes and relationships of the modified field.

```json
{
  "type": "field",
  "id": "Pkg-oztERp6o-Rj76nYKJg",
  "attributes": {
    "label": "Title",
    "field_type": "string",
    "api_key": "title",
    "localized": true,
    "validators": { "required": {} },
    "position": 1,
    "hint": "This field will be used as post title",
    "default_value": { "en": "A default value", "it": "Un valore di default" },
    "appearance": {
      "editor": "single_line",
      "parameters": { "heading": false },
      "addons": [{ "id": "1234", "field_extension": "lorem_ipsum", "parameters": {} }]
    },
    "deep_filtering_enabled": true
  },
  "relationships": {
    "item_type": { "data": { "type": "item_type", "id": "DxMaW10UQiCmZcuuA-IkkA" } },
    "fieldset": { "data": null }
  }
}

```

--------------------------------

### Current User Response Example

Source: https://www.datocms.com/docs/content-management-api/resources/user/me

This is an example of the JSON response you can expect when retrieving the current user's details. It includes user ID, email, full name, and role information.

```json
{
  id: "312",
  email: "mark.smith@example.com",
  is_2fa_active: true,
  full_name: "Mark Smith",
  is_active: true,
  role: { type: "role", id: "34" },
}

```

--------------------------------

### Session Creation Response - JSON

Source: https://www.datocms.com/docs/content-management-api/resources/session/create

This is an example of the JSON response received after successfully creating a session.

```json
{
  "id": "eyJCJhbGci.eyJhaWwuY29tIn0.32wQOMci",
  "user": { "type": "account", "id": "312" }
}

```

--------------------------------

### Create a New Record - Basic Example

Source: https://www.datocms.com/docs/content-management-api/resources/item/create

Demonstrates the fundamental process of creating a new record. Specify the item type and provide values for the record's fields. Fields not explicitly set will use their default values.

```javascript
import { buildClient, inspectItem } from "@datocms/cma-client-node";
import * as Schema from "./schema.js";


/*
 * Book
 * ├─ title: string
 * ├─ genre: string
 * ├─ synopsis: text
 * └─ pages: integer
 */


async function run() {
  // Make sure the API token has access to the CMA, and is stored securely
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });


  const record = await client.items.create<Schema.Book>({
    item_type: Schema.Book.REF,
    title: "The JavaScript Guide",
    genre: "Programming",
    synopsis:
      "A comprehensive guide to modern JavaScript.\nPerfect for beginners and experts alike.",
    pages: 450,
  });


  console.log(inspectItem(record));
}

run();

```

```text
└ Item "E3eHzSH6QSGbTDmlKlSusw" (item_type: "UZyfjdBES8y2W2ruMEHSoA")
  ├ title: "The JavaScript Guide"
  ├ genre: "Programming"
  ├ synopsis: "A comprehensive guide to modern JavaScript.\nPerfect for beginners and experts..."
  └ pages: 450

```

--------------------------------

### Filter Audit Log events by action name prefix

Source: https://www.datocms.com/docs/content-management-api/resources/audit-log-event/query

Use the `begins_with` function in PartiQL to filter events where the action name starts with a specific string. This example includes all actions starting with 'fields'.

```sql
begins_with(action_name, 'fields')
```

--------------------------------

### Get Current vs. Published Item State (JavaScript)

Source: https://www.datocms.com/docs/content-management-api/resources/item/current_vs_published_state

Use this snippet to fetch the state comparison between the current and published versions of an item. Ensure you have the @datocms/cma-client-node package installed and your API token set as an environment variable.

```javascript
import { buildClient } from "@datocms/cma-client-node";

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

  const itemId = "hWl-mnkWRYmMCSTq4z_piQ";

  const item = await client.items.currentVsPublishedState(itemId);

  // Check the 'Returned output' tab for the result ☝️
  console.log(item);
}

run();
```

--------------------------------

### Create Workflow - Basic Example

Source: https://www.datocms.com/docs/content-management-api/resources/workflow/create

Demonstrates how to create a new workflow with a name, stages, and API key using the CMA client. Ensure your DATOCMS_API_TOKEN environment variable is set.

```javascript
import { buildClient } from "@datocms/cma-client-node";

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

  const workflow = await client.workflows.create({
    name: "Approval by editors required",
    stages: [
      { id: "waiting_for_review", name: "Waiting for review", initial: true },
    ],
    api_key: "approval_by_editors",
  });

  // Check the 'Returned output' tab for the result ☝️
  console.log(workflow);
}

run();

```

```json
{
  id: "uJzC2b6YQg-DW2A5edpQYQ",
  name: "Approval by editors required",
  stages: [
    { id: "waiting_for_review", name: "Waiting for review", initial: true },
  ],
  api_key: "approval_by_editors",
}

```

--------------------------------

### Subscription Feature Object Example

Source: https://www.datocms.com/docs/content-management-api/resources/subscription-feature/instances

This is an example of the structure of a subscription feature object returned by the API.

```json
{ id: "locales", code: "sso", enabled: true }

```

--------------------------------

### Create Upload Track - Basic Example

Source: https://www.datocms.com/docs/content-management-api/resources/upload-track/create

Demonstrates how to create a new upload track with a URL, type, and language code. Ensure the DATOCMS_API_TOKEN environment variable is set.

```javascript
import { buildClient } from "@datocms/cma-client-node";

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

  const uploadId = "xBe7u01029ipxBLQhYzZCJ1cke01zCkuUsgnYtH0017nNzbpv2YcsoMDmw";

  const uploadTrack = await client.uploadTracks.create(uploadId, {
    url_or_upload_request_id: "/7/1455102967-image.png",
    type: "subtitles",
    language_code: "it-IT",
  });

  // Check the 'Returned output' tab for the result ☝️
  console.log(uploadTrack);
}

run();

```

--------------------------------

### List all deploy events with pagination

Source: https://www.datocms.com/docs/content-management-api/resources/build-event/instances

This example demonstrates how to iterate over all deploy events using the `listPagedIterator` method. Ensure your DATOCMS_API_TOKEN environment variable is set.

```javascript
import { buildClient } from "@datocms/cma-client-node";

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

  // iterates over every page of results
  for await (const buildEvent of client.buildEvents.listPagedIterator()) {
    // Check the 'Returned output' tab for the result ☝️
    console.log(buildEvent);
  }
}

run();

```

--------------------------------

### Trigger a Deploy - Basic Example

Source: https://www.datocms.com/docs/content-management-api/resources/build-trigger/trigger

This snippet shows how to trigger a build deploy using the CMA client. Ensure your DATOCMS_API_TOKEN environment variable is set.

```javascript
import { buildClient } from "@datocms/cma-client-node";

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

  const buildTriggerId = "1822";
  await client.buildTriggers.trigger(buildTriggerId);
}

run();

```

--------------------------------

### Install Public Plugin

Source: https://www.datocms.com/docs/content-management-api/resources/plugin/create

Installs a public plugin from NPM into the CMS. This allows users to easily add pre-built functionalities.

```APIDOC
## POST /plugins/install

### Description
Installs a public plugin from NPM.

### Method
POST

### Endpoint
/plugins/install

### Request Body
- **packageName** (string) - Required - The name of the NPM package for the plugin.
- **version** (string) - Optional - The specific version of the plugin to install. Defaults to the latest version.

### Request Example
{
  "packageName": "my-cms-plugin",
  "version": "1.2.3"
}

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating successful installation.
- **pluginId** (string) - The unique identifier of the installed plugin.

#### Response Example
{
  "message": "Plugin 'my-cms-plugin' installed successfully.",
  "pluginId": "plg_abc123def456"
}
```

--------------------------------

### Fork Environment Basic Example

Source: https://www.datocms.com/docs/content-management-api/resources/environment/fork

This snippet demonstrates how to fork an existing environment using the CMA client. It initializes the client, specifies the environment ID to fork, and calls the fork method. The result is then logged to the console.

```javascript
import { buildClient } from "@datocms/cma-client-node";

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

  const environmentId = "main";

  const environment = await client.environments.fork(environmentId, {});

  // Check the 'Returned output' tab for the result ☝️
  console.log(environment);
}

run();

```

--------------------------------

### Webhook Update Response Example

Source: https://www.datocms.com/docs/content-management-api/resources/webhook/update

This is an example of the JSON output returned after successfully updating a webhook. It includes all the fields of the webhook resource.

```json
{
  "id": "312",
  "name": "Item type creation/update",
  "url": "https://www.example.com/webhook",
  "enabled": true,
  "headers": { "X-Foo": "Bar" },
  "events": [{ "entity_type": "item", "event_types": ["update"] }],
  "http_basic_user": "user",
  "http_basic_password": "password",
  "custom_payload": '{ "message": "{{event_type}} event triggered on {{entity_type}}!", "entity_id": "{{#entity}}{{id}}{{/entity}}"] }',
  "payload_api_version": "3",
  "nested_items_in_payload": true,
  "auto_retry": true,
}

```

--------------------------------

### Returned Output for Tree Structure Creation

Source: https://www.datocms.com/docs/content-management-api/resources/item/create

Example output showing the created items, including their IDs, item types, names, positions, and parent IDs, illustrating the established hierarchy.

```text
└ Item "Ov5N1h4_QwW89_IzbUBb4g" (item_type: "UZyfjdBES8y2W2ruMEHSoA")
  ├ name: "Parent"
  ├ position: 1
  └ parent_id: null

└ Item "a8A-nl0cRXCqBNniQMAxog" (item_type: "UZyfjdBES8y2W2ruMEHSoA")
  ├ name: "Child 1"
  ├ position: 1
  └ parent_id: "Ov5N1h4_QwW89_IzbUBb4g"

└ Item "d6Gl9tPMSTqSF2bOMIcOYw" (item_type: "UZyfjdBES8y2W2ruMEHSoA")
  ├ name: "Child 2"
  ├ position: 2
  └ parent_id: "Ov5N1h4_QwW89_IzbUBb4g"

```

--------------------------------

### List Upload Tracks - Basic Example

Source: https://www.datocms.com/docs/content-management-api/resources/upload-track/instances

Lists all upload tracks for a given upload ID. Ensure the DATOCMS_API_TOKEN environment variable is set.

```javascript
import { buildClient } from "@datocms/cma-client-node";

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

  const uploadId = "xBe7u01029ipxBLQhYzZCJ1cke01zCkuUsgnYtH0017nNzbpv2YcsoMDmw";

  const uploadTracks = await client.uploadTracks.list(uploadId);

  for (const uploadTrack of uploadTracks) {
    // Check the 'Returned output' tab for the result ☝️
    console.log(uploadTrack);
  }
}

run();

```

```json
{
  id: "xBe7u01029ipxBLQhYzZCJ1cke01zCkuUsgnYtH0017nNzbpv2YcsoMDmw",
  type: "subtitles",
  name: "Italiano",
  language_code: "it-IT",
  closed_captions: false,
  status: "ready",
  error: null,
  upload: { type: "upload", id: "q0VNpiNQSkG6z0lif_O1zg" },
}

```

--------------------------------

### Update Site Example

Source: https://www.datocms.com/docs/content-management-api/resources/site/update

This snippet demonstrates how to update a site's configuration using the Datocms CMA client. Ensure your DATOCMS_API_TOKEN environment variable is set.

```javascript
import { buildClient } from "@datocms/cma-client-node";

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

  const site = await client.site.update({});

  // Check the 'Returned output' tab for the result ☝️
  console.log(site);
}

run();

```

--------------------------------

### Example Response for Referenced Records

Source: https://www.datocms.com/docs/content-management-api/resources/item/references

This is an example of the JSON payload returned when querying for records that reference a specific item. It includes item details and metadata.

```json
{
  "id": "hWl-mnkWRYmMCSTq4z_piQ",
  "title": "My first blog post!",
  "content": "Lorem ipsum dolor sit amet...",
  "category": "24",
  "image": {
    "alt": "Alt text",
    "title": "Image title",
    "custom_data": {},
    "focal_point": null,
    "upload_id": "20042921"
  },
  "meta": {
    "created_at": "2020-04-21T07:57:11.124Z",
    "updated_at": "2020-04-21T07:57:11.124Z",
    "published_at": "2020-04-21T07:57:11.124Z",
    "first_published_at": "2020-04-21T07:57:11.124Z",
    "publication_scheduled_at": "2020-04-21T07:57:11.124Z",
    "unpublishing_scheduled_at": "2020-04-21T07:57:11.124Z",
    "status": "published",
    "is_current_version_valid": true,
    "is_published_version_valid": true,
    "current_version": "4234",
    "stage": null,
    "has_children": true
  },
  "item_type": {
    "type": "item_type",
    "id": "DxMaW10UQiCmZcuuA-IkkA"
  }
}

```

--------------------------------

### Example Webhook Call Response

Source: https://www.datocms.com/docs/content-management-api/resources/webhook-call/instances

This is an example of the JSON output returned when listing webhook calls. It includes details about the request, response, and the event that triggered the webhook.

```json
[
  {
    id: "84033321",
    type: "webhook_call",
    request_url: "https://www.example.com/webhook",
    request_payload: '{ \
      "environment": "main", \
      "entity_type": "item", \
      "event_type": "create", \
      "entity": { \
        "id": "Ke9nrZ4iRHWpKbJplG_zdQ", \
        "type": "item", \
        "attributes": { \
          "text_field": "Test" \
        }, \
        "relationships": { \
          "item_type": { \
            "data": { \
              "id": "Dq4WEbdjStWIeSeH_lBA-Q", \
              "type": "item_type" \
            } \
          }, \
          "creator": { \
            "data": { \
              "id": "104280", \
              "type": "account" \
            } \
          } \
        }, \
        "meta": { \
          "created_at": "2024-04-03T22:47:43.488+01:00", \
          "updated_at": "2024-04-03T22:47:43.496+01:00", \
          "published_at": "2024-04-03T22:47:43.532+01:00", \
          "publication_scheduled_at": null, \
          "unpublishing_scheduled_at": null, \
          "first_published_at": "2024-04-03T22:47:43.532+01:00", \
          "is_valid": true, \
          "is_current_version_valid": true, \
          "is_published_version_valid": true, \
          "status": "published", \
          "current_version": "QXuPXVc6SDmXcDh1MnImHQ", \
          "stage": null \
        } \
      }, \
      "related_entities": [ \
        { \
          "id": "Dq4WEbdjStWIeSeH_lBA-Q", \
          "type": "item_type", \
          "attributes": { \
            "name": "Example Model", \
            "singleton": true, \
            "sortable": false, \
            "api_key": "example_model", \
            "ordering_direction": null, \
            "ordering_meta": null, \
            "tree": false, \
            "modular_block": false, \
            "draft_mode_active": false, \
            "all_locales_required": false, \
            "collection_appearance": "table", \
            "has_singleton_item": true, \
            "hint": null, \
            "inverse_relationships_enabled": false \
          }, \
          "relationships": { \
            "fields": { \
              "data": [ \
                { \
                  "id": "TuzswqxpQXyzJGv_3JtBAA", \
                  "type": "field" \
                } \
              ] \
            }, \
            "fieldsets": { \
              "data": [] \
            }, \
            "singleton_item": { \
              "data": { \
                "id": "Ke9nrZ4iRHWpKbJplG_zdQ", \
                "type": "item" \
              } \
            }, \
            "ordering_field": { \
              "data": null \
            }, \
            "title_field": { \
              "data": { \
                "id": "TuzswqxpQXyzJGv_3JtBAA", \
                "type": "field" \
              } \
            }, \
            "image_preview_field": { \
              "data": null \
            }, \
            "excerpt_field": { \
              "data": null \
            }, \
            "workflow": { \
              "data": null \
            } \
          }, \
          "meta": { \
            "has_singleton_item": true \
          } \
        } \
      ] \
    }',
    request_headers: {
      Accept: "*/*",
      "X-Site-Id": "128378",
      "User-Agent": "DatoCMS (datocms.com)",
      "Content-Type": "application/json",
      "X-Webhook-Id": "27321",
      "X-Environment": "main",
    },
    response_status: 200,
    response_headers: {
      date: "Wed, 03 Apr 2024 21:47:44 GMT",
      "content-length": "2",
    },
    created_at: "2024-04-03T21:47:44.093Z",
    response_payload: "OK",
    entity_type: "item",
    event_type: "create",
    webhook: { id: "27321", type: "webhook" },
  },
  // etc
]

```

--------------------------------

### Retrieve Environment Basic Example

Source: https://www.datocms.com/docs/content-management-api/resources/environment/self

Use this snippet to fetch a specific environment by its ID. Ensure you have initialized the client with your API token.

```javascript
import { buildClient } from "@datocms/cma-client-node";

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

  const environmentId = "main";

  const environment = await client.environments.find(environmentId);

  // Check the 'Returned output' tab for the result ☝️
  console.log(environment);
}

run();

```

--------------------------------

### Update Build Trigger - Basic Example

Source: https://www.datocms.com/docs/content-management-api/resources/build-trigger/update

This example demonstrates how to update a build trigger by its ID. Ensure you have your API token set in the environment variable DATOCMS_API_TOKEN.

```javascript
import { buildClient } from "@datocms/cma-client-node";

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

  const buildTriggerId = "1822";

  const buildTrigger = await client.buildTriggers.update(buildTriggerId, {
    id: "1822",
  });

  // Check the 'Returned output' tab for the result ☝️
  console.log(buildTrigger);
}
```

```json
{
  id: "1822",
  name: "Custom build trigger",
  adapter: "custom",
  adapter_settings: {
    trigger_url: "http://some-url.com/trigger",
    headers: { Authorization: "Bearer abc123" },
    payload: { type: "build_request" },
  },
  last_build_completed_at: "2017-03-30T09:29:14.872Z",
  build_status: "success",
  webhook_url: "https://webhooks.datocoms.com/xA1239ajsk123/deploy-results",
  frontend_url: "https://www.mywebsite.com/",
  enabled: true,
  autotrigger_on_scheduled_publications: true,
}
```

--------------------------------

### Create Schema Menu Item - Basic Example

Source: https://www.datocms.com/docs/content-management-api/resources/schema-menu-item/create

This snippet demonstrates how to create a basic schema menu item for an item type. Ensure you have your API token set in the environment variable DATOCMS_API_TOKEN.

```javascript
import { buildClient } from "@datocms/cma-client-node";

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

  const schemaMenuItem = await client.schemaMenuItems.create({
    label: "Posts",
    kind: "item_type",
  });

  // Check the 'Returned output' tab for the result ☝️
  console.log(schemaMenuItem);
}

run();

```

```json
{
  id: "uinr2zfqQLeCo_1O0-ao-Q",
  label: "Posts",
  position: 1,
  kind: "item_type",
  item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" },
  parent: null,
  children: [{ type: "schema_menu_item", id: "uinr2zfqQLeCo_1O0-ao-Q" }]
}

```

--------------------------------

### Scheduled Unpublishing Response Example

Source: https://www.datocms.com/docs/content-management-api/resources/scheduled-unpublishing/create

This is an example of the resource object returned after successfully creating a scheduled unpublishing entry. It includes the ID, scheduled time, and locale information.

```json
{
  "id": "34",
  "unpublishing_scheduled_at": "2025-02-10T11:03:42Z",
  "content_in_locales": ["en"],
  "item": { "type": "item", "id": "hWl-mnkWRYmMCSTq4z_piQ" }
}

```

--------------------------------

### Install a Public Plugin from NPM

Source: https://www.datocms.com/docs/content-management-api/resources/plugin/create

Use this snippet to install a public plugin by specifying its NPM package name. Ensure your API token has the necessary CMA access.

```javascript
import {
  buildClient
} from "@datocms/cma-client-node";


async function run() {
  // Make sure the API token has access to the CMA, and is stored securely
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });

  const plugin = await client.plugins.create({
    package_name: "datocms-plugin-star-rating-editor",
  });

  console.log(plugin);
}


run();

```