# Management SDK methods reference

Explore detailed reference of how to create, update, and delete fields using the Hygraph Management SDK. This guide covers models, simple fields, relational fields, remote sources, enumerations, components, and more. Each example includes code snippets and parameter breakdowns, ensuring you can implement and configure fields effectively within your Hygraph project.

This document is a quick reference for every operation that you can carry out using the Management SDK. For a tutorial-style guide, see [this document](https://hygraph.com/docs/api-reference/management-sdk/management-sdk-example).

All `Create`, `Update`, and `Delete` actions require **Update and Delete Existing Fields** permissions set in the Permanent Auth Token.

## Important notes

**Data loss warnings:**
- Converting fields to/from lists (`isList`) may cause data loss for existing entries.
- Changing `isRequired` to true requires `migrationValue` for existing entries with null values.
- Using `isUnique` with `initialValue` or `migrationValue` is forbidden (unique values must differ per entry).
- Converting field types may result in data loss or validation failures.

**Cardinality (Relational fields):**
- Relation cardinality is set at creation and cannot be changed later.
- `isList: false` + reverse `isList: false` = one-to-one.
- `isList: false` + reverse `isList: true` = one-to-many.
- `isList: true` + reverse `isList: true` = many-to-many.
- For components: reverse side must have `isList: true` to allow reconnection.

**Naming conventions:**
- Models/components: `PascalCase` (Examples: `BlogPost`, `SeoMetadata`)
- Fields: `camelCase` (Examples: `title`, `publishedAt`)
- Enumerations: `PascalCase` (Examples: `PostStatus`)
- Enum values: `UPPER_SNAKE_CASE` (Examples: `DRAFT`, `PUBLISHED`)

## Supported operations

All operations that can be executed by the SDK are listed in the TypeScript Type Definitions, [Client.d.ts](https://unpkg.com/@hygraph/management-sdk@latest/dist/src/Client.d.ts) file.

## Models

### createModel()

Creates a new content model.

**Use cases:**
- Setting up new content types for your application, such as `BlogPost`, `Product`, `Author`.
- Creating models for different content sections, such as `Pages`, `Articles`, `Events`.
- Initializing models with custom sidebar elements from apps, such as `Analytics Dashboard`, `Content Workflows`, `Variants`.

**Important notes:**
- `apiId` and `apiIdPlural` must be different (cannot be the same value).
- `apiId` must be PascalCase and start with uppercase letter.
- Models must have unique `apiId` and `displayName` within an environment.
- Cannot create required fields on system models/components.
- Sidebar elements can be added during creation or via `updateModel`.

  **Parameters**

```ts
client.createModel({
  apiId: string,                    // Required: The model API ID
  apiIdPlural: string,              // Required: The plural API ID (used for lists)
  displayName: string,               // Required: Display name shown in the webapp
  description?: string,             // Optional: Description of the model
  isSystem?: boolean,               // Optional: Only AppTokens should provide this flag
  sidebarElements?: Array<{         // Optional: Sidebar elements to create
    displayName: string,             // Required: Display name for the sidebar element
    description?: string,           // Optional: Description for the sidebar element
    config?: JSON,                  // Optional: JSON metadata associated with the sidebar element
    appElementApiId: string,        // Required: API ID of the App element
    appApiId: string,               // Required: API ID of the App
    position?: number               // Optional: Position of the sidebar element
  }>
})
```

  
  **Examples**

```ts
// Basic model creation
client.createModel({
  apiId: 'Post',
  apiIdPlural: 'Posts',
  displayName: 'Blog Post',
  description: 'Blog posts for the website',
});

// Model with custom sidebar elements
client.createModel({
  apiId: 'Product',
  apiIdPlural: 'Products',
  displayName: 'Product',
  description: 'E-commerce products',
  sidebarElements: [
    {
      displayName: 'Product Analytics',
      description: 'View product analytics',
      appElementApiId: 'analytics-dashboard',
      appApiId: 'analytics-app',
      position: 0,
      config: { refreshInterval: 30 },
    },
  ],
});
```


### updateModel()

Updates an existing content model.

**Use cases:**
- Renaming models (using `newApiId`).
- Updating model descriptions or display names
- Managing sidebar elements (adding, updating, removing custom and system sidebar elements).
- Adding app integrations to models.

**Important notes:**
- Renaming with newApiId updates all references to the model.
- Sidebar elements can be managed via sidebarElementsToUpsert structure.
- System sidebar elements include: `INFORMATION`, `STAGES`, `LOCALIZATIONS`, `VERSIONS`, `PREVIEW_URLS`, `RELEASES`, `CONTENT_WORKFLOWS`, `VARIANTS`.
- Custom sidebar elements require `appApiId` and `appElementApiId`.

  **Parameters**

```ts
client.updateModel({
  apiId: string,                    // Required: Current API ID of the model
  newApiId?: string,                // Optional: New API ID (to rename the model)
  apiIdPlural?: string,             // Optional: New plural API ID
  displayName?: string,              // Optional: New display name
  description?: string,              // Optional: New description
  isSystem?: boolean,                // Optional: System model flag (only for AppTokens)
  sidebarElementsToUpsert?: {       // Optional: Sidebar elements to create/update/delete
    customSidebarElementsToCreate?: Array<{
      displayName: string,           // Required: Display name
      description?: string,          // Optional: Description
      config?: JSON,                 // Optional: JSON metadata
      appElementApiId: string,       // Required: API ID of the App element
      appApiId: string,              // Required: API ID of the App
      position?: number              // Optional: Position
    }>,
    systemSidebarElementsToCreate?: Array<{
      type: SystemSidebarElementType, // Required: System sidebar element type
      config?: JSON,                 // Optional: JSON metadata
      position?: number              // Optional: Position
    }>,
    sidebarElementsToUpdate?: Array<{
      displayName: string,           // Required: Current display name (identifier)
      newDisplayName?: string,       // Optional: New display name
      description?: string,          // Optional: New description
      config?: JSON,                 // Optional: New config
      position?: number              // Optional: New position
    }>,
    customSidebarElementsToDelete?: Array<{
      appApiId: string,              // Required: API ID of the App
      appElementApiId: string        // Required: API ID of the App element
    }>,
    systemSidebarElementsToDelete?: Array<{
      type: SystemSidebarElementType // Required: System sidebar element type
    }>
  }
})
```

  
  **Examples**

```ts
// Basic update - rename model and change display name
client.updateModel({
  apiId: 'Post',
  newApiId: 'BlogPost',
  displayName: 'Blog Post',
  description: 'Updated description',
});

// Update with sidebar elements management
client.updateModel({
  apiId: 'Product',
  displayName: 'Product',
  sidebarElementsToUpsert: {
    customSidebarElementsToCreate: [
      {
        displayName: 'Product Analytics',
        description: 'View analytics',
        appElementApiId: 'analytics-dashboard',
        appApiId: 'analytics-app',
        position: 0,
      },
    ],
    systemSidebarElementsToCreate: [
      {
        type: SystemSidebarElementType.INFORMATION,
        position: 1,
      },
    ],
    sidebarElementsToUpdate: [
      {
        displayName: 'Product Analytics',
        newDisplayName: 'Analytics Dashboard',
        description: 'Updated analytics dashboard',
        position: 2,
      },
    ],
    customSidebarElementsToDelete: [
      {
        appApiId: 'old-app',
        appElementApiId: 'old-element',
      },
    ],
    systemSidebarElementsToDelete: [
      {
        type: SystemSidebarElementType.VERSIONS,
      },
    ],
  },
});
```


- `SystemSidebarElementType` - `INFORMATION`, `STAGES`, `LOCALIZATIONS`, `VERSIONS`, `PREVIEW_URLS`, `RELEASES`, `CONTENT_WORKFLOWS`, `VARIANTS`

### deleteModel()

Deletes a content model.

**Use cases:**
- Removing unused content models.
- Cleaning up test/development models.
- Restructuring content architecture.

**Important notes:**
- Permanent deletion. This action cannot be undone.
- Deletes all entries in the model.
- Deletes all fields associated with the model.
- Delete the model only if there are no other models that depend on it.

  **Parameter**

```ts
client.deleteModel({
  apiId: string  // Required: The API ID of the model to delete
})
```

  
  **Example**

```ts
// Delete a model
client.deleteModel({
  apiId: 'Post',
});

console.log('Model deleted');
```


## Simple fields

### createSimpleField()

Creates a simple field on a model or component.

**Use cases:**
- Adding text fields (title, description, content), such as `title`, `description`, `content` in the `Post` model .
- Creating date/time fields (publishedAt, eventDate), such as `publishedAt`, `eventDate` in the `Post` model.
- Setting up boolean flags (featured, published, active), such as `featured`, `published`, `active` in the `Post` model.
- Creating numeric fields (price, rating, count), such as `price`, `rating`, `count` in the `Post` model.
- Adding rich text content fields, such as `content` in the `Post` model.
- Creating slug fields with auto-generation, such as `slug` in the `Post` model.
- Setting up email/URL fields with validation, such as `email`, `url` in the `Post` model.
- Creating hidden fields for internal tracking, such as `internalTracking` in the `Post` model.

**Important notes:**
- Field `apiId` must be camelCase and start with lowercase letter.
- Reserved field names: `createdAt`, `createdBy`, `documentInStages`, `history`, `id`, `locale`, `localizations`, `publish`, `publishedAt`, `publishedBy`, `status`, `updatedAt`, `updatedBy`, `versions`.
- `isUnique: true` cannot be combined with `initialValue` or `migrationValue`.
- RichText fields cannot be marked as title (`isTitle: true`).
- List RichText fields cannot be required (`isList: true + isRequired: true`).
- ID type fields are validated as CUIDs and stored as `varchar(25)`.
- `initialValue` must be stringified for non-string types (e.g., `'false'` for boolean).

  **Parameters**

```ts
client.createSimpleField({
  apiId: string,                    // Required: Field API ID
  parentApiId: string,              // Required: API ID of parent model/component (use instead of modelApiId)
  modelApiId?: string,              // Deprecated: Use parentApiId instead
  type: SimpleFieldType,            // Required: Field type enum
  displayName: string,              // Required: Display name
  description?: string,             // Optional: Description
  isVariantEnabled?: boolean,       // Optional: Enable variant support
  initialValue?: string,            // Optional: Default value (stringified for non-strings)
  tableRenderer?: string,           // Optional: Table renderer identifier
  formRenderer?: string,           // Optional: Form renderer identifier. Supported values: `GCMS_SINGLE_LINE`, `GCMS_MULTI_LINE`, `GCMS_SLUG`, or `GCMS_MARKDOWN`
  tableExtension?: string,          // Optional: Table extension identifier
  formExtension?: string,           // Optional: Form extension identifier
  formConfig?: JSON,                // Optional: Form configuration JSON
  tableConfig?: JSON,               // Optional: Table configuration JSON
  isList?: boolean,                 // Optional: Whether field accepts multiple values (default: false)
                                  // WARNING: Converting existing fields to/from list may cause data loss
  isLocalized?: boolean,            // Optional: Whether field is localized (default: false)
  isRequired?: boolean,             // Optional: Whether field is required (default: false)
                                    // When changing existing field to true, must provide migrationValue
  isUnique?: boolean,               // Optional: Whether field is unique (default: false)
                                    // CANNOT be combined with initialValue or migrationValue
                                    // Unique values must differ per entry
  isHidden?: boolean,               // Deprecated: Use visibility instead
  visibility?: VisibilityTypes,    // Optional: Visibility setting
  isTitle?: boolean,                // Optional: Whether field is used as title (default: false)
  position?: number,                // Optional: Field position
  validations?: {                   // Optional: Field validations with custom error messages
    Int?: {
      range?: {                     // Validate numeric range
        min?: number,               // Minimum value (inclusive)
        max?: number,               // Maximum value (inclusive)
        errorMessage?: string       // Custom error shown to users
      },
      listItemCount?: {             // Validate list length (when isList is true)
        min?: number,               // Minimum items required
        max?: number,               // Maximum items allowed
        errorMessage?: string
      }
    },
    String?: {
      characters?: {                // Validate string length
        min?: number,               // Minimum characters
        max?: number,               // Maximum characters
        errorMessage?: string
      },
      matches?: {                   // Validate with regex pattern (must match)
        regex: string,              // Regex pattern (e.g., email format)
        flags?: string[],           // Regex flags (e.g., ['i'] for case-insensitive)
        errorMessage?: string
      },
      notMatches?: {                // Validate with regex pattern (must NOT match)
        regex: string,              // Regex pattern to reject
        flags?: string[],
        errorMessage?: string
      }
    }
  },
  migrationValue?: string,          // Optional: Value to set for existing null entries
                                    // Required when changing isRequired to true on existing fields
                                    // Cannot be combined with isUnique (unique values must differ per entry)
  embedsEnabled?: boolean,          // Optional: Enable rich text embeds
  embeddableModels?: string[],     // Required when embedsEnabled is true
                                    // Array of model API IDs that can be embedded
  visibilityCondition?: {           // Optional: Conditional visibility - show/hide field based on another field's value
    baseField: string,              // Required: API ID of the field that controls visibility
    operator: FieldConditionOperator, // Required: Comparison operator (IS, IS_NOT, etc.)
    enumerationValues?: string[],   // Required when baseField is enumeration type
    booleanValue?: boolean          // Required when baseField is boolean type
  },
  isSystem?: boolean                // Optional: System field flag (only for AppTokens)
})
```

  
  **Examples**

```ts
// Basic string field
client.createSimpleField({
  parentApiId: 'Post',
  apiId: 'title',
  displayName: 'Title',
  type: SimpleFieldType.STRING,
  isRequired: true,
  isTitle: true,
});

// String field with validations
client.createSimpleField({
  parentApiId: 'Post',
  apiId: 'slug',
  displayName: 'Slug',
  type: SimpleFieldType.STRING,
  isRequired: true,
  isUnique: true,
  validations: {
    String: {
      characters: { max: 100, errorMessage: 'Slug must be under 100 characters' },
      matches: { regex: '^[a-z0-9-]+$', flags: [], errorMessage: 'Invalid slug format' },
    },
  },
});

// Slug field with validations
client.createSimpleField({
  parentApiId: 'Page',
  type: SimpleFieldType.STRING,
  apiId: 'slug',
  displayName: 'Slug',
  description: 'Enter the slug for this page, such as about, blog, or contact',
  isRequired: true,
  isUnique: true,
  tableRenderer: 'GCMS_SLUG',
  formRenderer: 'GCMS_SLUG',
  validations: {
    String: {
      characters: {
        max: 100,
        errorMessage: 'Slug must be under 100 characters'
      },
      matches: {
        regex: '^[a-z0-9-]+$',
        flags: [],
        errorMessage: 'Slug can only contain lowercase letters, numbers, and hyphens'
      },
    },
  },
});

// Richtext field
client.createSimpleField({
  parentApiId: '<parent_api_id>',
  type: SimpleFieldType.RICHTEXT,
  apiId: '<api_id>',
  displayName: '<Display Name>',
  description:
    '<Enter the content for this page. The content uses the rich-text editor.>',
  isRequired: true,
});

// Rich text field with embeds
client.createSimpleField({
  parentApiId: 'Post',
  apiId: 'content',
  displayName: 'Content',
  type: SimpleFieldType.RICHTEXT,
  embedsEnabled: true,
  embeddableModels: ['Author', 'Image'],
});

// Boolean field with initial value
client.createSimpleField({
  parentApiId: 'Post',
  apiId: 'featured',
  displayName: 'Featured',
  type: SimpleFieldType.BOOLEAN,
  isRequired: true,
  initialValue: 'false', // Must be stringified
});

// Hidden integer field with custom field validation
client.createSimpleField({
  parentApiId: 'Product',
  type: SimpleFieldType.INT,
  apiId: 'viewCount',
  displayName: 'View Count',
  visibility: VisibilityTypes.HIDDEN,
  validations: {
    Int: {
      range: {
        max: 1000,
        min: 0,
        errorMessage: 'Counter has to be between 0 and 1000',
      },
    },
  },
});

// Required and unique email field with validation
client.createSimpleField({
  parentApiId: 'User',
  type: SimpleFieldType.STRING,
  apiId: 'email',
  displayName: 'Email',
  description: 'User email address',
  isRequired: true,
  isUnique: true,
  validations: {
    String: {
      matches: {
        regex: '^([a-z0-9_\\.\\+-]+)@([\\da-z\\.-]+)\\.([a-z\\.]{2,6})$',
        flags: ['i'], // Case-insensitive matching
        errorMessage: 'Please enter a valid email address',
      },
    },
  },
});

// Create a list of date times for event dates
client.createSimpleField({
  parentApiId: 'Post',
  type: SimpleFieldType.DATETIME,
  apiId: 'scheduledPublishDates',
  displayName: 'Scheduled Publish Dates',
  description: 'Multiple dates when this post should be published',
  isRequired: false,
  isList: true,
});

// Add a field to a component
client.createSimpleField({
  parentApiId: 'SeoMetadata',
  type: SimpleFieldType.STRING,
  apiId: 'metaTitle',
  displayName: 'Meta Title',
});
```


**Enums**

- `SimpleFieldType`: `ID`, `STRING`, `RICHTEXT`, `INT`, `FLOAT`, `BOOLEAN`, `JSON`, `DATETIME`, `DATE`, `LOCATION`, `COLOR`
- `VisibilityTypes`: `READ_WRITE`, `READ_ONLY`, `HIDDEN`, `API_ONLY`
- `FieldConditionOperator`: `IS`, `IS_NOT`, `CONTAINS_ANY`, `CONTAINS_ALL`, `CONTAINS_NONE`

### updateSimpleField()

Updates an existing simple field.

**Use cases:**
- Renaming fields
- Adding/updating validations
- Changing field visibility
- Updating embeddable models for rich text fields
- Adding conditional visibility
- Changing required/unique status

**Important notes:**
- Field type cannot be changed (immutable).
- `embeddableModels` uses add/remove structure: `{ modelsToAdd: [], modelsToRemove: [] }`.
- When changing `isRequired` to true, must provide `migrationValue` for existing null entries.
- Cannot change `isList` without potential data loss.
- `visibilityCondition` can be set to `null` to remove it.

  **Parameters**

```ts
client.updateSimpleField({
  apiId: string,                    // Required: Current field API ID
  newApiId?: string,                // Optional: New API ID (to rename the field)
  parentApiId?: string,             // Optional: Parent model/component API ID (use instead of modelApiId)
  modelApiId?: string,              // Deprecated: Use parentApiId instead
  displayName?: string,             // Optional: New display name
  description?: string,             // Optional: New description
  isVariantEnabled?: boolean,       // Optional: Enable/disable variant support
  isList?: boolean,                 // Optional: Whether field accepts multiple values (default: false)
                                    // WARNING: Converting existing fields to/from list may cause data loss
  isLocalized?: boolean,            // Optional: Whether field is localized
  isRequired?: boolean,             // Optional: Whether field is required
                                    // When changing to true, provide migrationValue for existing null entries
  isUnique?: boolean,               // Optional: Whether field is unique
                                    // CANNOT be used with initialValue or migrationValue
  isHidden?: boolean,               // Deprecated: Use visibility instead
  visibility?: VisibilityTypes,    // Optional: Visibility setting
  isTitle?: boolean,                // Optional: Whether field is used as title
  position?: number,                // Optional: Field position
  initialValue?: string,            // Optional: Default value (stringified)
  migrationValue?: string,          // Optional: Migration value for existing data
                                    // Required when changing isRequired to true on existing fields
  validations?: {                   // Optional: Field validations (same structure as create)
    Int?: {
      range?: {
        min?: number,
        max?: number,
        errorMessage?: string
      },
      listItemCount?: {
        min?: number,
        max?: number,
        errorMessage?: string
      }
    },
    Float?: {
      range?: {
        min?: number,
        max?: number,
        errorMessage?: string
      },
      listItemCount?: {
        min?: number,
        max?: number,
        errorMessage?: string
      }
    },
    String?: {
      characters?: {
        min?: number,
        max?: number,
        errorMessage?: string
      },
      listItemCount?: {
        min?: number,
        max?: number,
        errorMessage?: string
      },
      matches?: {
        regex: string,
        flags?: string[],
        errorMessage?: string
      },
      notMatches?: {
        regex: string,
        flags?: string[],
        errorMessage?: string
      }
    }
  },
  embedsEnabled?: boolean,          // Optional: Enable rich text embeds
  embeddableModels?: {              // Optional: Manage embeddable models (different from create)
    modelsToAdd?: string[],         // Model API IDs to add to existing list
    modelsToRemove?: string[]       // Model API IDs to remove from existing list
  },                                 // NOTE: Different structure from create!
  tableRenderer?: string,           // Optional: Table renderer identifier
  formRenderer?: string,           // Optional: Form renderer identifier. Supported values: `GCMS_SINGLE_LINE`, `GCMS_MULTI_LINE`, `GCMS_SLUG`, or `GCMS_MARKDOWN`
  tableExtension?: string,          // Optional: Table extension identifier
  formExtension?: string,           // Optional: Form extension identifier
  formConfig?: JSON,                // Optional: Form configuration JSON
  tableConfig?: JSON,               // Optional: Table configuration JSON
  visibilityCondition?: {           // Optional: Show/hide field based on another field's value
    baseField: string,              // Required: API ID of the field that controls visibility
    operator: FieldConditionOperator, // Required: Comparison operator (IS, IS_NOT, etc.)
    enumerationValues?: string[],   // Required when baseField is enumeration type
    booleanValue?: boolean          // Required when baseField is boolean type
  },
  isSystem?: boolean                // Optional: System field flag (only for AppTokens)
})
```

  
  **Examples**

```ts
// Basic update - rename field and change display name
client.updateSimpleField({
  apiId: 'title',
  newApiId: 'postTitle',
  displayName: 'Post Title',
});

// Update validations
client.updateSimpleField({
  apiId: 'slug',
  validations: {
    String: {
      characters: { max: 150, errorMessage: 'Slug must be under 150 characters' },
    },
  },
});

// Update embeddable models (add/remove models)
client.updateSimpleField({
  apiId: 'content',
  embedsEnabled: true,
  embeddableModels: {
    modelsToAdd: ['Video', 'Quote'],
    modelsToRemove: ['Image'],
  },
});
```


**Enums**

- `SimpleFieldType`: `ID`, `STRING`, `RICHTEXT`, `INT`, `FLOAT`, `BOOLEAN`, `JSON`, `DATETIME`, `DATE`, `LOCATION`, `COLOR`
- `VisibilityTypes`: `READ_WRITE`, `READ_ONLY`, `HIDDEN`, `API_ONLY`
- `FieldConditionOperator`: `IS`, `IS_NOT`, `CONTAINS_ANY`, `CONTAINS_ALL`, `CONTAINS_NONE`

### deleteField()

Deletes one of the following field types from a model or component:

    <div className="flex flex-col md:flex-row md:gap-4">
      <div className="flex-1">
        - Simple fields
        - Enumerable fields
        - Component fields
        - Component union fields
      </div>
      <div className="flex-1">
        - Relational fields
        - Union fields
        - Remote fields
        - Taxonomy fields
      </div>
    </div>

**Use cases:**
- Removing unused fields.
- Cleaning up deprecated fields.
- Restructuring content models.

**Important notes:**
- Permanent deletion. This action cannot be undone.
- Deletes all field data for all entries.
- May break conditional visibility dependencies.
- Cannot delete required fields (make optional first).

  **Parameters**

```ts
client.deleteField({
  apiId: string,        // Required: The API ID of the field to delete
  parentApiId?: string, // Optional: API ID of parent model/component (use instead of modelApiId)
  modelApiId?: string   // Deprecated: Use parentApiId instead
})
```

  
  **Example**

```ts
// Delete a simple field
client.deleteField({
  apiId: 'title',
  parentApiId: 'Post',
});

// Delete an enumerable field
client.deleteField({
  apiId: 'status',
  parentApiId: 'Post',
});

// Delete a component field
client.deleteField({
  apiId: 'seoMetadata',
  parentApiId: 'Post',
});

// Delete a component union field
client.deleteField({
  apiId: 'relatedPosts',
  parentApiId: 'Post',
});

// Delete a relational field
client.deleteField({
  apiId: 'author',
  parentApiId: 'Post',
});

// Delete a union field
client.deleteField({
  apiId: 'relatedPosts',
  parentApiId: 'Post',
});

// Delete a remote field
client.deleteField({
  apiId: 'externalData',
  parentApiId: 'Post',
});

// Delete a taxonomy field
client.deleteField({
  apiId: 'category',
  parentApiId: 'Post',
});

console.log('Field deleted');
```


## Enumerations

### createEnumeration()

Creates a new enumeration (enum) with its values.

**Use cases:**
- Creating status enums (`DRAFT`, `PUBLISHED`, `ARCHIVED`)
- Setting up category types (`NEWS`, `BLOG`, `TUTORIAL`)
- Defining content types (`ARTICLE`, `VIDEO`, `PODCAST`)
- Creating priority levels (`LOW`, `MEDIUM`, `HIGH`, `URGENT`)

**Important notes:**
- Enumeration `apiId` must be PascalCase.
- Enum values must be UPPER_SNAKE_CASE, such as, `DRAFT`, `PUBLISHED`.
- Enumeration `apiId` and `displayName` must be unique within environment.
- Enum values are referenced by their `apiId` in enumerable fields.

  **Parameters**

```ts
client.createEnumeration({
  apiId: string,                    // Required: Enumeration API ID
  displayName: string,              // Required: Display name
  description?: string,             // Optional: Description
  values: Array<{                   // Required: Array of enum values
    apiId: string,                  // Required: Value API ID
    displayName: string             // Required: Value display name
  }>,
  isSystem?: boolean               // Optional: System enumeration flag (only for AppTokens)
})
```
  
  **Examples**

```ts
// Basic enumeration with status values
client.createEnumeration({
  apiId: 'PostStatus',
  displayName: 'Post Status',
  description: 'Publication status for blog posts',
  values: [
    { apiId: 'DRAFT', displayName: 'Draft' },
    { apiId: 'REVIEW', displayName: 'In Review' },
    { apiId: 'PUBLISHED', displayName: 'Published' },
  ],
});

// Priority enumeration
client.createEnumeration({
  apiId: 'Priority',
  displayName: 'Priority',
  description: 'Task priority levels',
  values: [
    { apiId: 'LOW', displayName: 'Low' },
    { apiId: 'MEDIUM', displayName: 'Medium' },
    { apiId: 'HIGH', displayName: 'High' },
    { apiId: 'URGENT', displayName: 'Urgent' },
  ],
});
```


### updateEnumeration()

Updates an existing enumeration and its values.

**Use cases:**
- Adding new enum values.
- Updating enum value display names.
- Removing enum values.

**Important notes:**
- Enum values are managed via `valuesToAdd` and `valuesToRemove`.
- Cannot change enum `apiId` directly (use `newApiId`).
- Removing enum values may break existing entries using those values.

  **Parameters**

```ts
client.updateEnumeration({
  apiId: string,                    // Required: Current enumeration API ID
  newApiId?: string,                // Optional: New API ID (to rename the enumeration)
  displayName?: string,             // Optional: New display name
  description?: string,             // Optional: New description
  valuesToCreate?: Array<{          // Optional: New enum values to add
    apiId: string,                  // Required: Value API ID
    displayName: string             // Required: Value display name
  }>,
  valuesToUpdate?: Array<{          // Optional: Existing enum values to update
    apiId: string,                  // Required: Current value API ID
    newApiId?: string,              // Optional: New value API ID (to rename)
    displayName?: string            // Optional: New display name
  }>,
  valuesToDelete?: string[],        // Optional: Array of value API IDs to delete
  isSystem?: boolean               // Optional: System enumeration flag (only for AppTokens)
})
```

  
  **Examples**

```ts
// Rename enumeration and update display name
client.updateEnumeration({
  apiId: 'PostStatus',
  newApiId: 'ArticleStatus',
  displayName: 'Article Status',
  description: 'Updated description',
});

// Add new enum values
client.updateEnumeration({
  apiId: 'PostStatus',
  valuesToCreate: [
    { apiId: 'ARCHIVED', displayName: 'Archived' },
    { apiId: 'SCHEDULED', displayName: 'Scheduled' },
  ],
});

// Update existing enum values
client.updateEnumeration({
  apiId: 'PostStatus',
  valuesToUpdate: [
    {
      apiId: 'REVIEW',
      newApiId: 'IN_REVIEW',
      displayName: 'In Review',
    },
  ],
});

// Delete enum values
client.updateEnumeration({
  apiId: 'PostStatus',
  valuesToDelete: ['ARCHIVED', 'SCHEDULED'],
});
```


### deleteEnumeration()

Deletes an enumeration.

**Use cases:**
- Removing unused enumerations.
- Cleaning up deprecated enums.

**Important notes:**
- Permanent deletion. This action cannot be undone.
- Cannot delete if used by enumerable fields.
- Must delete all enumerable fields using the enumeration first.

  **Parameter**

```ts
client.deleteEnumeration({
  apiId: string  // Required: The API ID of the enumeration to delete
})
```

  
  **Example**

```ts
// Delete an enumeration
client.deleteEnumeration({
  apiId: 'PostStatus',
});

console.log('Enumeration deleted');
```


### createEnumerableField()

Creates an enumerable field (enum field) on a model or component.

**Use cases:**
- Adding status fields to content models.
- Creating category/type selection fields.
- Setting up priority/rating fields.

**Important notes:**
- `enumerationApiId` must reference an existing enumeration.
- `initialValue` must be the enum value `apiId` (not `displayName`).
- Cannot use `isUnique` with `initialValue` or `migrationValue`.

  **Parameters**

```ts
client.createEnumerableField({
  apiId: string,                    // Required: Field API ID
  parentApiId: string,              // Required: API ID of parent model/component (use instead of modelApiId)
  modelApiId?: string,              // Deprecated: Use parentApiId instead
  enumerationApiId: string,         // Required: API ID of the enumeration to use
  displayName: string,              // Required: Display name
  description?: string,             // Optional: Description
  isVariantEnabled?: boolean,       // Optional: Enable variant support
  tableRenderer?: string,           // Optional: Table renderer identifier
  formRenderer?: string,            // Optional: Form renderer identifier
  tableExtension?: string,          // Optional: Table extension identifier
  formExtension?: string,           // Optional: Form extension identifier
  isList?: boolean,                 // Optional: Whether field accepts multiple values (default: false)
                                    // WARNING: Converting existing fields to/from list may cause data loss
  isLocalized?: boolean,            // Optional: Whether field is localized (default: false)
  isRequired?: boolean,             // Optional: Whether field is required (default: false)
                                    // When changing to true, provide migrationValue for existing null entries
  isUnique?: boolean,               // Optional: Whether field is unique (default: false)
                                    // CANNOT be used with initialValue or migrationValue
  isHidden?: boolean,               // Deprecated: Use visibility instead
  visibility?: VisibilityTypes,    // Optional: Visibility setting
  isTitle?: boolean,                // Optional: Whether field is used as title (default: false)
  position?: number,               // Optional: Field position
  migrationValue?: string,          // Optional: Migration value for existing data (enum value API ID)
  initialValue?: string,            // Optional: Default value (enum value API ID, stringified)
  visibilityCondition?: {           // Optional: Show/hide field based on another field's value
  baseField: string,              // Required: API ID of the field that controls visibility
  operator: FieldConditionOperator, // Required: Comparison operator (IS, IS_NOT, etc.)
  enumerationValues?: string[],   // Required when baseField is enumeration type
  booleanValue?: boolean          // Required when baseField is boolean type
  },
  isSystem?: boolean                // Optional: System field flag (only for AppTokens)
})
```

  
  **Examples**

```ts
// Basic enumerable field
client.createEnumerableField({
  parentApiId: 'Post',
  apiId: 'status',
  displayName: 'Status',
  enumerationApiId: 'PostStatus',
  isRequired: true,
  initialValue: 'DRAFT', // Enum value API ID
});

// Enumerable field with list support
client.createEnumerableField({
  parentApiId: 'Post',
  apiId: 'tags',
  displayName: 'Tags',
  enumerationApiId: 'PostTag',
  isList: true,
  isRequired: false,
});
```


**Enums**
- `VisibilityTypes`: `READ_WRITE`, `READ_ONLY`, `HIDDEN`, `API_ONLY`
- `FieldConditionOperator`: `IS`, `IS_NOT`, `CONTAINS_ANY`, `CONTAINS_ALL`, `CONTAINS_NONE`

### updateEnumerableField()

Updates an existing enumerable field.

**Use cases:**
- Changing enumeration reference
- Updating field visibility
- Adding conditional visibility

**Important notes:**
- Can change `enumerationApiId` to reference a different enumeration.
- Must ensure new enumeration has compatible values.

  **Parameters**

```ts
client.updateEnumerableField({
  apiId: string,                    // Required: Current field API ID
  newApiId?: string,                // Optional: New API ID (to rename the field)
  parentApiId?: string,             // Optional: Parent model/component API ID
  displayName?: string,             // Optional: New display name
  description?: string,             // Optional: New description
  isVariantEnabled?: boolean,       // Optional: Enable/disable variant support
  isList?: boolean,                 // Optional: Whether field accepts multiple values (default: false)
                                    // WARNING: Converting existing fields to/from list may cause data loss
  isLocalized?: boolean,            // Optional: Whether field is localized
  isRequired?: boolean,             // Optional: Whether field is required
                                    // When changing to true, provide migrationValue for existing null entries
  isUnique?: boolean,               // Optional: Whether field is unique
                                    // CANNOT be used with initialValue or migrationValue
  isHidden?: boolean,               // Deprecated: Use visibility instead
  visibility?: VisibilityTypes,    // Optional: Visibility setting
  isTitle?: boolean,                // Optional: Whether field is used as title
  position?: number,                // Optional: Field position
  initialValue?: string,            // Optional: Default value (enum value API ID, stringified)
  migrationValue?: string,          // Optional: Migration value for existing data
  visibilityCondition?: {           // Optional: Show/hide field based on another field's value
    baseField: string,              // Required: API ID of the field that controls visibility
    operator: FieldConditionOperator, // Required: Comparison operator (IS, IS_NOT, etc.)
    enumerationValues?: string[],   // Required when baseField is enumeration type
    booleanValue?: boolean          // Required when baseField is boolean type
  },
  isSystem?: boolean                // Optional: System field flag (only for AppTokens)
})
```

  
  **Examples**

```ts
// Basic update - rename field and change display name
client.updateEnumerableField({
  apiId: 'status',
  newApiId: 'publicationStatus',
  displayName: 'Publication Status',
  description: 'Current publication status',
});

// Update initial value
client.updateEnumerableField({
  apiId: 'status',
  initialValue: 'PUBLISHED', // Enum value API ID
});

// Update visibility
client.updateEnumerableField({
  apiId: 'status',
  visibility: VisibilityTypes.READ_ONLY,
});
```


**Enums**
- `VisibilityTypes`: `READ_WRITE`, `READ_ONLY`, `HIDDEN`, `API_ONLY`
- `FieldConditionOperator`: `IS`, `IS_NOT`, `CONTAINS_ANY`, `CONTAINS_ALL`, `CONTAINS_NONE`

## Components

### createComponent()

Creates a new component.

**Use cases:**
- Creating reusable field groups (`SEO metadata`, `contact info`, `address`).
- Building modular content blocks (`CTA`, `image block`, `video block`).
- Setting up shared field structures across multiple models.

**Important notes:**
- Component `apiId` must be PascalCase.
- `apiId` and `apiIdPlural` must be different.
- Components can be nested (components can contain other components).
- Components cannot have required fields if used in multiple places.

  **Parameters**

```ts
client.createComponent({
  apiId: string,                    // Required: Component API ID
  apiIdPlural: string,              // Required: Plural API ID (used for lists)
  displayName: string,              // Required: Display name shown in the webapp
  description?: string              // Optional: Description of the component
})
```

  
  **Examples**

```ts
// Basic component creation
client.createComponent({
  apiId: 'SeoMetadata',
  apiIdPlural: 'SeoMetadatas',
  displayName: 'SEO Metadata',
  description: 'Search engine optimization fields',
});

// Contact details component
client.createComponent({
  apiId: 'ContactDetails',
  apiIdPlural: 'ContactDetailsCollection',
  displayName: 'Contact Details',
  description: 'Phone and email contact information',
});
```


### updateComponent()

Updates an existing component.

**Use cases:**
- Renaming components.
- Updating descriptions.
- Managing component fields.

**Important notes:**
- Renaming updates all references to the component.
- Cannot change `apiId` directly (use `newApiId`).

  **Parameters**

```ts
client.updateComponent({
  apiId: string,                    // Required: Current component API ID
  newApiId?: string,                // Optional: New API ID (to rename the component)
  apiIdPlural?: string,             // Optional: New plural API ID
  displayName?: string,             // Optional: New display name
  description?: string              // Optional: New description
})
```

  
  **Examples**

```ts
// Basic update - rename component and change display name
client.updateComponent({
  apiId: 'SeoMetadata',
  newApiId: 'SeoMeta',
  displayName: 'SEO Meta',
  description: 'Updated SEO metadata fields',
});

// Update only display name
client.updateComponent({
  apiId: 'ContactDetails',
  displayName: 'Contact Information',
});

// Update plural API ID
client.updateComponent({
  apiId: 'AuthorInfo',
  apiIdPlural: 'AuthorInfoCollection',
});
```


### deleteComponent()

Deletes a component.

**Use cases:**
- Removing unused components.
- Cleaning up deprecated components.

**Important notes:**
- Permanent deletion. This action cannot be undone.
- Cannot delete if used by any models or components.
- Must delete all component fields using the component first

  **Parameters**

```ts
client.deleteComponent({
  apiId: string  // Required: The API ID of the component to delete
})
```

  
  **Example**

```ts
// Delete a component
client.deleteComponent({
  apiId: 'SeoMetadata',
});

console.log('Component deleted');
```


### createComponentField()

Creates a component field that embeds a component into a model or another component.

**Use cases:**
- Embedding reusable components into models.
- Adding SEO metadata to content models.
- Including contact information components.

**Important notes:**
- `parentApiId` can be a model or another component (for nesting).
- `componentApiId` references the component to embed.
- `isList: true` allows multiple instances of the component.

  **Parameters**

```ts
client.createComponentField({
  apiId: string,                    // Required: Field API ID
  parentApiId: string,              // Required: API ID of parent model/component
  componentApiId: string,           // Required: API ID of the component to embed
  displayName: string,              // Required: Display name
  description?: string,             // Optional: Description
  isVariantEnabled?: boolean,       // Optional: Enable variant support
  tableRenderer?: string,           // Optional: Table renderer identifier
  formRenderer?: string,            // Optional: Form renderer identifier
  tableExtension?: string,         // Optional: Table extension identifier
  formExtension?: string,           // Optional: Form extension identifier
  isList?: boolean,                 // Optional: Whether field accepts multiple values (default: false)
                                    // WARNING: Converting existing fields to/from list may cause data loss
  isRequired?: boolean,             // Optional: Whether field is required (default: false)
                                    // When changing to true, provide migrationValue for existing null entries
  visibility?: VisibilityTypes,    // Optional: Visibility setting
  position?: number,               // Optional: Field position
  visibilityCondition?: {           // Optional: Show/hide field based on another field's value
    baseField: string,              // Required: API ID of the field that controls visibility
    operator: FieldConditionOperator, // Required: Comparison operator (IS, IS_NOT, etc.)
    enumerationValues?: string[],   // Required when baseField is enumeration type
    booleanValue?: boolean          // Required when baseField is boolean type
  },
})
```

    
  **Examples**

```ts
// Basic component field - embed SEO component in Post model
client.createComponentField({
  parentApiId: 'Post',
  apiId: 'seo',
  displayName: 'SEO',
  componentApiId: 'SeoMetadata',
  isRequired: false,
});

// Component field as a list
client.createComponentField({
  parentApiId: 'Post',
  apiId: 'contentBlocks',
  displayName: 'Content Blocks',
  componentApiId: 'ImageBlock',
  isList: true,
  isRequired: false,
});

// Nested component - embed component inside another component
client.createComponentField({
  parentApiId: 'AuthorInfo', // Component API ID
  apiId: 'contact',
  displayName: 'Contact',
  componentApiId: 'ContactDetails', // Another component
  isRequired: false,
});

// Create basic component field
client.createComponentField({
  parentApiId: 'Post',
  apiId: 'seo',
  displayName: 'SEO',
  description: 'Search engine optimization metadata',
  componentApiId: 'SeoMetadata',
});
```


**Enums**
- `VisibilityTypes`: `READ_WRITE`, `READ_ONLY`, `HIDDEN`, `API_ONLY`
- `FieldConditionOperator`: `IS`, `IS_NOT`, `CONTAINS_ANY`, `CONTAINS_ALL`, `CONTAINS_NONE`

### updateComponentField()

Updates an existing component field.

**Use cases:**
- Renaming component fields.
- Changing component reference
- Updating field visibility
- Adding conditional visibility.
- Changing required status.

**Important notes:**
- Can change `componentApiId` to reference a different component.
- Cannot change `isList` without potential data loss.
- When changing `isRequired` to `true`, must provide `migrationValue` for existing null entries.
- `visibilityCondition` can be set to `null` to remove it.

  **Parameters**

```ts
client.updateComponentField({
  apiId: string,                    // Required: Current field API ID
  parentApiId: string,              // Required: Parent model/component API ID
  newApiId?: string,                // Optional: New API ID (to rename the field)
  displayName?: string,             // Optional: New display name
  description?: string,             // Optional: New description
  isList?: boolean,                 // Optional: Whether field accepts multiple values (default: false)
                                    // WARNING: Converting existing fields to/from list may cause data loss
  isRequired?: boolean,             // Optional: Whether field is required
                                    // When changing to true, provide migrationValue for existing null entries
  visibility?: VisibilityTypes,    // Optional: Visibility setting
  isVariantEnabled?: boolean,       // Optional: Enable/disable variant support
  position?: number,                // Optional: Field position
  visibilityCondition?: {           // Optional: Show/hide field based on another field's value
    baseField: string,              // Required: API ID of the field that controls visibility
    operator: FieldConditionOperator, // Required: Comparison operator (IS, IS_NOT, etc.)
    enumerationValues?: string[],   // Required when baseField is enumeration type
    booleanValue?: boolean          // Required when baseField is boolean type
  },
})
```

  
  **Examples**

```ts
// Basic update - rename field and change display name
client.updateComponentField({
  apiId: 'seo',
  parentApiId: 'Post',
  newApiId: 'seoMetadata',
  displayName: 'SEO Metadata',
  description: 'Search engine optimization fields',
});

// Update to make field required
client.updateComponentField({
  apiId: 'seo',
  parentApiId: 'Post',
  isRequired: true,
});

// Update visibility
client.updateComponentField({
  apiId: 'seo',
  parentApiId: 'Post',
  visibility: VisibilityTypes.READ_ONLY,
});
```


**Enums**
- `VisibilityTypes`: `READ_WRITE`, `READ_ONLY`, `HIDDEN`, `API_ONLY`
- `FieldConditionOperator`: `IS`, `IS_NOT`, `CONTAINS_ANY`, `CONTAINS_ALL`, `CONTAINS_NONE`

### createComponentUnionField()

Creates a modular component field that allows editors to choose from multiple component types.

**Use cases:**
- Building flexible page builders.
- Creating modular content systems.
- Allowing content editors to choose from multiple component types.

**Important notes:**
- `componentApiIds` must contain at least one component.
- Allows selecting from multiple component types in a single field.
- Useful for flexible, modular content structures.
- Content editors choose which component type to use per entry.

  **Parameters**

```ts
client.createComponentUnionField({
  // Required parameters
  apiId: string,                    // Field API ID (camelCase)
  parentApiId: string,              // API ID of parent model (PascalCase)
  displayName: string,              // Display name shown in UI
  componentApiIds: string[],        // Array of component API IDs (PascalCase) - at least one required

  // Optional parameters
  description?: string,             // Description text
  isVariantEnabled?: boolean,       // Enable variant support
  tableRenderer?: string,          // Table renderer identifier
  formRenderer?: string,           // Form renderer identifier
  tableExtension?: string,          // Table extension identifier
  formExtension?: string,           // Form extension identifier
  isList?: boolean,                 // Whether field accepts multiple values (default: false)
                                    // WARNING: Converting existing fields to/from list may cause data loss
  isRequired?: boolean,             // Whether field is required (default: false)
  visibility?: VisibilityTypes,      // Visibility setting
  visibilityCondition?: {           // Conditional visibility
    baseField: string,              // API ID of the field that controls visibility
    operator: FieldConditionOperator, // Comparison operator
    enumerationValues?: string[],   // Required when baseField is enumeration type
    booleanValue?: boolean          // Required when baseField is boolean type
  },
  position?: number                 // Field position
})
```

  
  **Examples**

```ts
// Complete example - creating components and union field
// 1. Create individual components
client.createComponent({
  apiId: 'CallToAction',
  apiIdPlural: 'CallToActions',
  displayName: 'Call to Action',
  description: 'CTA block with button',
});

client.createComponent({
  apiId: 'ImageBlock',
  apiIdPlural: 'ImageBlocks',
  displayName: 'Image Block',
  description: 'Image with caption',
});

client.createComponent({
  apiId: 'VideoBlock',
  apiIdPlural: 'VideoBlocks',
  displayName: 'Video Block',
  description: 'Video embed block',
});

// 2. Add fields to components
client.createSimpleField({
  parentApiId: 'CallToAction',
  type: SimpleFieldType.STRING,
  apiId: 'heading',
  displayName: 'Heading',
  isRequired: true,
});

client.createSimpleField({
  parentApiId: 'ImageBlock',
  type: SimpleFieldType.STRING,
  apiId: 'imageUrl',
  displayName: 'Image URL',
  isRequired: true,
});

// 3. Create the union field that allows any of these components
client.createComponentUnionField({
  parentApiId: 'Post',
  apiId: 'contentBlocks',
  displayName: 'Content Blocks',
  description: 'Flexible content blocks for rich posts',
  componentApiIds: ['CallToAction', 'ImageBlock', 'VideoBlock'],
  isList: true,
  isRequired: false,
});

// Landing page sections (conditional visibility)
client.createComponentUnionField({
  parentApiId: 'Post',
  apiId: 'contentBlocks',
  displayName: 'Content Blocks',
  componentApiIds: ['CallToAction', 'ImageBlock'],
  visibilityCondition: {
    baseField: 'status',
    operator: FieldConditionOperator.IS,
    enumerationValues: ['PUBLISHED'],
  },
});
```


**Enums**
- `VisibilityTypes`: `READ_WRITE`, `READ_ONLY`, `HIDDEN`, `API_ONLY`
- `FieldConditionOperator`: `IS`, `IS_NOT`, `CONTAINS_ANY`, `CONTAINS_ALL`, `CONTAINS_NONE`

### updateComponentUnionField()

Updates a modular component field.

**Use cases:**
- Adding new component types to union.
- Removing component types from union.
- Updating which components are available.

**Important notes:**
- `componentApiIds` replaces the entire list.
- To remove a component, provide complete list WITHOUT it.
- To add a component, provide complete list INCLUDING it.
- Cannot change `isList` or `isRequired` (not available in update)

  **Parameters**

```ts
client.updateComponentUnionField({
  // Required parameters
  apiId: string,                    // Current field API ID
  parentApiId: string,              // Parent model API ID

  // Optional parameters
  newApiId?: string,                // New API ID (to rename the field)
  displayName?: string,             // New display name
  description?: string,             // New description
  isVariantEnabled?: boolean,       // Enable/disable variant support
  componentApiIds?: string[],       // Array of component API IDs - REPLACES entire list
                                    // To remove a component, provide the complete list WITHOUT it
  visibilityCondition?: {           // Conditional visibility
    baseField: string,              // API ID of the field that controls visibility
    operator: FieldConditionOperator, // Comparison operator
    enumerationValues?: string[],   // Required when baseField is enumeration type
    booleanValue?: boolean          // Required when baseField is boolean type
  },
  position?: number                 // Field position
})
```

  
  **Examples**

```ts

// Basic update - rename field
client.updateComponentUnionField({
  apiId: 'contentBlocks',
  parentApiId: 'Post',
  newApiId: 'postContentBlocks',
  displayName: 'Post Content Blocks',
});

// Remove component from a component union field
client.updateComponentUnionField({
  apiId: '<api_id>',
  parentApiId: '<parent_api_id>',
  componentApiIds: [
    '<contributor_component_api_id>',
    // VideoBlock removed - only include components you want to keep
  ],
});

// Add a component to the union

// Original: ['CallToAction', 'ImageBlock'. Add VideoBlock - provide complete list INCLUDING VideoBlock
client.updateComponentUnionField({
  apiId: 'contentBlocks',
  parentApiId: 'Post',
  componentApiIds: [
    'CallToAction',
    'ImageBlock',
    'VideoBlock', // Added
  ],
});

// Update multiple properties
client.updateComponentUnionField({
  apiId: 'contentBlocks',
  parentApiId: 'Post',
  newApiId: 'sections',
  displayName: 'Page Sections',
  description: 'Flexible page sections',
  componentApiIds: ['HeroSection', 'FeaturesSection', 'TestimonialsSection'],
});

// Add conditional visibility
client.updateComponentUnionField({
  apiId: 'contentBlocks',
  parentApiId: 'Post',
  visibilityCondition: {
    baseField: 'status',
    operator: FieldConditionOperator.IS,
    enumerationValues: ['PUBLISHED'],
  },
});

// Remove conditional visibility
client.updateComponentUnionField({
  apiId: 'contentBlocks',
  parentApiId: 'Post',
  visibilityCondition: null, // Removes the visibility condition
});

// Modify component list

// Original union field with: ['CallToAction', 'ImageBlock', 'VideoBlock']

// Remove VideoBlock and add QuoteBlock
client.updateComponentUnionField({
  apiId: 'contentBlocks',
  parentApiId: 'Post',
  componentApiIds: [
    'CallToAction',
    'ImageBlock',
    'QuoteBlock', // Added
    // VideoBlock removed
  ],
});

```


**Enums**
- `FieldConditionOperator`: `IS`, `IS_NOT`, `CONTAINS_ANY`, `CONTAINS_ALL`, `CONTAINS_NONE`

## Relational fields

### createRelationalField()

Creates a relational field that links models together (relation) or to assets (asset).

**Use cases:**
- Linking models together (`Post → Author`, `Product → Category`).
- Connecting content to assets (`Post → Featured Image`).
- Creating many-to-many relations (`Post ↔ Category`).
- Setting up one-to-many relations (`Author → Posts`).

**Important notes:**
- Cardinality is immutable. It is set at creation and cannot be changed later.
- `isRequired: true` is ONLY supported for ASSET type, not RELATION type.
- `reverseField.modelApiId` is the TARGET model being referenced.
- For unidirectional relations, `reverseField.position` should be negative.
- For components, `reverseField.isList` must be true to allow reconnection.

**Note:**

Relation cardinality is set at creation and **cannot be changed later**. You cannot convert:
- One-to-one → One-to-many
- One-to-many → Many-to-many
- Any other cardinality changes

If you need a different cardinality, you must delete and recreate the relation (which may cause data loss).

**For components and unidirectional relations:** The reverse side must have `isList: true` to allow reconnecting entries to the same component instance. Setting `isList: false` will prevent reconnection and may require recreating the relation.

  **Parameters**

```ts
client.createRelationalField({
  apiId: string,                    // Required: Field API ID
  parentApiId: string,              // Required: API ID of parent model (use instead of modelApiId)
  modelApiId?: string,              // Deprecated: Use parentApiId instead
  type: RelationalFieldType,        // Required: RELATION or ASSET
  displayName: string,              // Required: Display name
  description?: string,             // Optional: Description
  isVariantEnabled?: boolean,       // Optional: Enable variant support
  tableRenderer?: string,           // Optional: Table renderer identifier
  formRenderer?: string,            // Optional: Form renderer identifier
  tableExtension?: string,          // Optional: Table extension identifier
  formExtension?: string,           // Optional: Form extension identifier
  isList?: boolean,                 // Optional: Whether THIS side accepts multiple values (default: false)
                                    // Combined with reverseField.isList determines cardinality:
                                      // - false + reverse false = one-to-one (this is parent)
                                      // - false + reverse true = one-to-many (this is child)
                                      // - true + reverse false = many-to-one (this is parent)
                                      // - true + reverse true = many-to-many
                                    // CANNOT be changed after creation!
  isRequired?: boolean,             // Optional: Whether field is required
                                  // ONLY valid for ASSET type. Regular RELATION fields cannot be required
  isHidden?: boolean,               // Deprecated: Use visibility instead
  visibility?: VisibilityTypes,    // Optional: Visibility setting
  formConfig?: JSON,                // Optional: Form configuration JSON
  tableConfig?: JSON,               // Optional: Table configuration JSON
  reverseField: {                   // Required: Configuration for the reverse side of the relation
    apiId: string,                  // Required: API ID for reverse field (appears on related model)
    modelApiId: string,             // Required: API ID of the related/target model
    displayName: string,            // Required: Display name for reverse field
    description?: string,           // Optional: Description for reverse field
    isList?: boolean,               // Optional: Whether reverse side accepts multiple values
                                    // IMPORTANT for components: Must be true to allow reconnection!
    isHidden?: boolean,             // Deprecated: Use visibility instead
    visibility?: VisibilityTypes,   // Optional: Visibility of reverse field
    isUnidirectional?: boolean,     // Optional: Create one-way relation (no reverse field shown in UI)
                                    // When true, related model won't display this relation
    position?: number               // Optional: Position of reverse field
                                    // MUST be negative for unidirectional relations
  },
  visibilityCondition?: {           // Optional: Show/hide field based on another field's value
    baseField: string,              // Required: API ID of the field that controls visibility
    operator: FieldConditionOperator, // Required: Comparison operator (IS, IS_NOT, etc.)
    enumerationValues?: string[],   // Required when baseField is enumeration type
    booleanValue?: boolean          // Required when baseField is boolean type
  },
  position?: number                 // Optional: Reverse field position
                                    // MUST be negative for unidirectional relations
})
```

  
  **Examples**

```ts
// Create a required uni-directional asset field
client.createRelationalField({
  parentApiId: 'Post',
  apiId: 'featuredImage',
  displayName: 'Featured Image',
  type: RelationalFieldType.ASSET,
  isRequired: true,
  reverseField: {
    isUnidirectional: true,
    apiId: 'featuredInPosts',
    displayName: 'Featured In Posts',
    modelApiId: 'Asset',
  },
});

// Create a many-to-many (M-N) relation
client.createRelationalField({
  parentApiId: 'Post',
  apiId: 'categories',
  displayName: 'Categories',
  type: RelationalFieldType.RELATION,
  isList: true,
  reverseField: {
    modelApiId: 'Category',
    apiId: 'posts',
    displayName: 'Posts',
    isList: true,
  },
});


// Basic relation - Post to Author (many-to-one)
client.createRelationalField({
  parentApiId: 'Post',
  apiId: 'author',
  displayName: 'Author',
  type: RelationalFieldType.RELATION,
  reverseField: {
    apiId: 'posts',
    modelApiId: 'Author',
    displayName: 'Posts',
    isList: true,
  },
});

// Asset relation - Post to featured image
client.createRelationalField({
  parentApiId: 'Post',
  apiId: 'featuredImage',
  displayName: 'Featured Image',
  type: RelationalFieldType.ASSET,
  isRequired: true, // isRequired is only supported for ASSET type
  reverseField: {
    apiId: 'featuredInPosts',
    modelApiId: 'Asset',
    displayName: 'Featured In Posts',
    isList: true,
  },
});
```


**Enums**

- `RelationalFieldType`: `RELATION`, `ASSET`
- `VisibilityTypes`: `READ_WRITE`, `READ_ONLY`, `HIDDEN`, `API_ONLY`
- `FieldConditionOperator`: `IS`, `IS_NOT`, `CONTAINS_ANY`, `CONTAINS_ALL`, `CONTAINS_NONE`

### updateRelationalField()

Updates an existing relational field.

**Use cases:**
- Making relations unidirectional.
- Updating field visibility.
- Changing required status (for `ASSET` type only).

**Important notes:**
- Cannot change cardinality (`isList` cannot be changed).
- `isRequired` can only be changed for `ASSET` type.
- `isUnidirectional` is a top-level parameter (not in `reverseField`).
- No `reverseField` parameter in update (the reverse field is managed separately).

  **Parameters**

```ts
client.updateRelationalField({
  apiId: string,                    // Required: Current field API ID
  newApiId?: string,               // Optional: New API ID (to rename the field)
  parentApiId?: string,            // Optional: Parent model API ID
  displayName?: string,             // Optional: New display name
  description?: string,             // Optional: New description
  isVariantEnabled?: boolean,      // Optional: Enable/disable variant support
  isList?: boolean,                 // Optional: Whether field accepts multiple values (default: false)
                                    // WARNING: Converting existing fields to/from list may cause data loss
  isRequired?: boolean,             // Optional: Whether field is required (only for ASSET type!)
                                    // When changing to true, provide migrationValue for existing null entries
  isHidden?: boolean,               // Deprecated: Use visibility instead
  visibility?: VisibilityTypes,    // Optional: Visibility setting
  isUnidirectional?: boolean,       // Optional: Make relation unidirectional
  formConfig?: JSON,                // Optional: Form configuration JSON
  tableConfig?: JSON,               // Optional: Table configuration JSON
  visibilityCondition?: {           // Optional: Show/hide field based on another field's value
    baseField: string,              // Required: API ID of the field that controls visibility
    operator: FieldConditionOperator, // Required: Comparison operator (IS, IS_NOT, etc.)
    enumerationValues?: string[],   // Required when baseField is enumeration type
    booleanValue?: boolean          // Required when baseField is boolean type
  },
  position?: number                 // Optional: Field position
})
```

  
  **Examples**

```ts
// Basic update - rename field and change display name
client.updateRelationalField({
  apiId: 'author',
  parentApiId: 'Post',
  newApiId: 'postAuthor',
  displayName: 'Post Author',
  description: 'Author of the post',
});

// Update to make field required (only for ASSET type)
client.updateRelationalField({
  apiId: 'featuredImage',
  parentApiId: 'Post',
  isRequired: true, // Only works for ASSET type
});

// Make relation unidirectional
client.updateRelationalField({
  apiId: 'relatedPosts',
  parentApiId: 'Post',
  isUnidirectional: true,
});
```


**Enums**

- `VisibilityTypes`: `READ_WRITE`, `READ_ONLY`, `HIDDEN`, `API_ONLY`
- `FieldConditionOperator`: `IS`, `IS_NOT`, `CONTAINS_ANY`, `CONTAINS_ALL`, `CONTAINS_NONE`

## Union fields

### createUnionField()

Creates a union field that links to multiple models (not components).

**Use cases:**
- Creating polymorphic relationships (`Post` can reference `Author` OR `Organization`).
- Allowing flexible model references.
- Building content that can link to multiple model types.

**Important notes:**
- `modelApiIds` must contain at least one model API ID.
- Allows selecting from multiple model types in a single field.
- `reverseField` is required and must specify `modelApiIds` array.
- Useful for polymorphic content relationships.

  **Parameters**

```ts
client.createUnionField({
  apiId: string,                    // Required: Field API ID
  parentApiId: string,              // Required: API ID of parent model (use instead of modelApiId)
  modelApiId?: string,              // Deprecated: Use parentApiId instead
  displayName: string,              // Required: Display name
  description?: string,             // Optional: Description
  isVariantEnabled?: boolean,       // Optional: Enable variant support
  tableRenderer?: string,           // Optional: Table renderer identifier
  formRenderer?: string,            // Optional: Form renderer identifier
  tableExtension?: string,          // Optional: Table extension identifier
  formExtension?: string,           // Optional: Form extension identifier
  isList?: boolean,                 // Optional: Whether field accepts multiple values (default: false)
                                    // WARNING: Converting existing fields to/from list may cause data loss
  isHidden?: boolean,               // Deprecated: Use visibility instead
  visibility?: VisibilityTypes,    // Optional: Visibility setting
  reverseField: {                   // Required: Reverse field configuration
    apiId?: string,                 // Optional: Reverse field API ID
    modelApiIds: string[],          // Required: Complete array of model API IDs
                                  // NOTE: Replaces entire list (not merged with existing!)
                                  // Must include all models you want to keep
    displayName?: string,           // Optional: Reverse field display name
    description?: string,           // Optional: Reverse field description
    isList?: boolean,               // Optional: Whether field accepts multiple values (default: false)
                                    // WARNING: Converting existing fields to/from list may cause data loss
    isHidden?: boolean,             // Deprecated: Use visibility instead
    visibility?: VisibilityTypes,   // Optional: Reverse field visibility
    positions?: Array<{             // Optional: Position for each model
      modelApiId: string,           // Required: Model API ID
      position: number              // Required: Display osition
    }>
  },
  visibilityCondition?: {           // Optional: Show/hide field based on another field's value
    baseField: string,              // Required: API ID of the field that controls visibility
    operator: FieldConditionOperator, // Required: Comparison operator (IS, IS_NOT, etc.)
    enumerationValues?: string[],   // Required when baseField is enumeration type
    booleanValue?: boolean          // Required when baseField is boolean type
  },
  position?: number                 // Optional: Field position
})
```

  
  **Examples**

```ts
// Basic union field - link to multiple models
client.createUnionField({
  parentApiId: 'Post',
  apiId: 'authorOrEditor',
  displayName: 'Author or Editor',
  reverseField: {
    modelApiIds: ['Author', 'Editor'],
    displayName: 'Posts',
    isList: true,
  },
});

// Union field with list support
client.createUnionField({
  parentApiId: 'Post',
  apiId: 'relatedContent',
  displayName: 'Related Content',
  isList: true,
  reverseField: {
    modelApiIds: ['Post', 'Page', 'Video'],
    displayName: 'Related From',
    isList: true,
  },
});
```


**Enums**

- `VisibilityTypes`: `READ_WRITE`, `READ_ONLY`, `HIDDEN`, `API_ONLY`
- `FieldConditionOperator`: `IS`, `IS_NOT`, `CONTAINS_ANY`, `CONTAINS_ALL`, `CONTAINS_NONE`

### updateUnionField()

Updates an existing union field.

**Use cases:**
- Adding or removing model types from union.
- Updating reverse field configuration.

**Important notes:**
- `modelApiIds` replaces the entire list.
- `reverseField.modelApiIds` can be updated.
- Cannot change entire `reverseField` structure.

  **Parameters**

```ts
client.updateUnionField({
  apiId: string,                    // Required: Current field API ID
  newApiId?: string,                // Optional: New API ID (to rename the field)
  parentApiId?: string,             // Optional: Parent model API ID
  displayName?: string,             // Optional: New display name
  description?: string,             // Optional: New description
  visibility?: VisibilityTypes,    // Optional: Visibility setting
  isVariantEnabled?: boolean,       // Optional: Enable/disable variant support
  position?: number,                 // Optional: Field position
  reverseField?: {                  // Optional: Update reverse field configuration
    modelApiIds: string[],          // Required: Array of model API IDs (complete list)
    positions?: Array<{             // Optional: Position for each model
      modelApiId: string,           // Required: Model API ID
      position: number              // Required: Position value
    }>
  },
  visibilityCondition?: {           // Optional: Show/hide field based on another field's value
    baseField: string,              // Required: API ID of the field that controls visibility
    operator: FieldConditionOperator, // Required: Comparison operator (IS, IS_NOT, etc.)
    enumerationValues?: string[],   // Required when baseField is enumeration type
    booleanValue?: boolean          // Required when baseField is boolean type
  },
})
```

  
  **Examples**


```ts
// Basic update - rename field and change display name
client.updateUnionField({
  apiId: 'authorOrEditor',
  parentApiId: 'Post',
  newApiId: 'contentAuthor',
  displayName: 'Content Author',
  description: 'Author or editor of the content',
});

// Update reverse field - change which models can be linked
client.updateUnionField({
  apiId: 'authorOrEditor',
  parentApiId: 'Post',
  reverseField: {
    modelApiIds: ['Author', 'Editor', 'Contributor'], // Complete list of models
  },
});

// Remove a model from the union (provide only models you want to keep)
client.updateUnionField({
  apiId: 'authorOrEditor',
  parentApiId: 'Post',
  reverseField: {
    modelApiIds: ['Author'], // Only Author remains, Editor is removed
  },
});
```


**Enums**

- `VisibilityTypes`: `READ_WRITE`, `READ_ONLY`, `HIDDEN`, `API_ONLY`
- `FieldConditionOperator`: `IS`, `IS_NOT`, `CONTAINS_ANY`, `CONTAINS_ALL`, `CONTAINS_NONE`

## Remote sources

### createGraphQLRemoteSource()

Creates a new GraphQL remote source.

**Use cases:**
- Integrating external GraphQL APIs.
- Connecting to commerce platforms (CommerceTools, CommerceLayer)
- Building federated content systems.

**Important notes:**
- `prefix` is immutable. It cannot be changed after creation.
- `prefix` is prepended to all remote types.
- `introspectionUrl` can differ from `url` if introspection is on different endpoint.
- `remoteTypeDefinitions` allows custom GraphQL types.
- `OAuth` configuration is optional but required for protected APIs.

  **Parameters**

```ts
client.createGraphQLRemoteSource({
  displayName: string,              // Required: Display name
  prefix: string,                    // Required: Unique prefix for remote types (cannot be changed!)
  url: string,                       // Required: GraphQL endpoint URL
  kind: RemoteSourceKind,           // Required: Remote source kind enum
  introspectionMethod: GraphQLRemoteSourceIntrospectionMethod, // Required: HTTP method for introspection
  description?: string,              // Optional: Description
  headers?: JSON,                    // Optional: Custom headers (JSON object)
  introspectionUrl?: string,        // Optional: Separate URL for introspection (if different from url)
  introspectionHeaders?: JSON,      // Optional: Headers for introspection (JSON object)
  remoteTypeDefinitions?: {         // Optional: Custom GraphQL type definitions
    sdl: string                      // Required: GraphQL SDL string
  },
  debugEnabled?: boolean,          // Optional: Enable debug mode
  oAuth?: {                         // Optional: OAuth configuration
    clientId: string,                // Required: OAuth client ID
    clientSecret?: string,           // Optional: OAuth client secret
    scopes?: string[],               // Optional: OAuth scopes
    authorizationGrantType: OAuthGrantType, // Required: OAuth grant type
    authorizationUrl: string        // Required: OAuth authorization URL
  }
})
```


  **Examples**

```ts
// Basic GraphQL remote source
client.createGraphQLRemoteSource({
  displayName: 'External GraphQL API',
  prefix: 'External',
  url: 'https://api.example.com/graphql',
  kind: RemoteSourceKind.Custom,
  introspectionMethod: GraphQLRemoteSourceIntrospectionMethod.POST,
});

// GraphQL remote source with headers
client.createGraphQLRemoteSource({
  displayName: 'Protected GraphQL API',
  prefix: 'Protected',
  url: 'https://api.example.com/graphql',
  kind: RemoteSourceKind.Custom,
  introspectionMethod: GraphQLRemoteSourceIntrospectionMethod.POST,
  headers: {
    Authorization: 'Bearer api-token',
    'X-API-Key': 'your-api-key',
  },
});

// GraphQL remote source with OAuth
client.createGraphQLRemoteSource({
  displayName: 'OAuth GraphQL API',
  prefix: 'OAuth',
  url: 'https://api.example.com/graphql',
  kind: RemoteSourceKind.Custom,
  introspectionMethod: GraphQLRemoteSourceIntrospectionMethod.POST,
  oAuth: {
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret',
    scopes: ['read:products', 'write:products'],
    authorizationGrantType: OAuthGrantType.client_credentials,
    authorizationUrl: 'https://auth.example.com/oauth/token',
  },
});
```


**Enums**

- `RemoteSourceKind`: `CommerceTools`, `CommerceLayer`, `Custom`
- `GraphQLRemoteSourceIntrospectionMethod`: `GET`, `POST`
- `OAuthGrantType`: `client_credentials`

### updateGraphQLRemoteSource()

Updates an existing GraphQL remote source.

**Use cases:**
- Updating remote source URLs.
- Changing authentication headers.
- Modifying OAuth configuration.
- Adding/updating remote type definitions.
- Updating introspection settings.

**Important notes:**
- `prefix` cannot be changed (immutable).
- `remoteTypeDefinitionsToUpsert` uses create/update/delete structure.
- OAuth configuration can be updated.
- `introspectionUrl` and `introspectionMethod` can be changed.
- Headers can be updated for authentication.

  **Parameters**

```ts
client.updateGraphQLRemoteSource({
  prefix: string,                   // Required: Remote source prefix (used to identify the source)
  displayName?: string,             // Optional: New display name
  description?: string,             // Optional: New description
  url?: string,                     // Optional: New GraphQL endpoint URL
  headers?: JSON,                   // Optional: Custom headers (JSON object)
  introspectionUrl?: string,       // Optional: Separate URL for introspection
  introspectionMethod?: GraphQLRemoteSourceIntrospectionMethod, // Optional: HTTP method for introspection
  introspectionHeaders?: JSON,     // Optional: Headers for introspection (JSON object)
  remoteTypeDefinitionsToUpsert?: { // Optional: Manage remote type definitions
    remoteTypeDefinitionsToCreate?: Array<{ // Optional: Create new type definitions
      sdl: string                    // Required: GraphQL SDL string
    }>,
    remoteTypeDefinitionsToUpdate?: Array<{ // Optional: Update existing type definitions
      apiId: string,                 // Required: Type definition API ID
      sdl?: string                   // Optional: New SDL string
    }>,
    remoteTypeDefinitionsToDelete?: Array<{ // Optional: Delete type definitions
      apiId: string                  // Required: Type definition API ID
    }>
  },
  debugEnabled?: boolean,          // Optional: Enable/disable debug mode
  kind?: RemoteSourceKind,         // Optional: Remote source kind enum
  oAuth?: {                         // Optional: OAuth configuration
    clientId: string,               // Required: OAuth client ID
    clientSecret?: string,          // Optional: OAuth client secret
    scopes?: string[],              // Optional: OAuth scopes
    authorizationGrantType: OAuthGrantType, // Required: OAuth grant type
    authorizationUrl: string        // Required: OAuth authorization URL
  }
})
```


  **Examples**

```ts
// Basic update - change display name and URL
client.updateGraphQLRemoteSource({
  prefix: 'External',
  displayName: 'Updated GraphQL API',
  url: 'https://api.example.com/new-graphql',
});

// Update headers
client.updateGraphQLRemoteSource({
  prefix: 'External',
  headers: {
    Authorization: 'Bearer new-token',
    'X-API-Key': 'new-api-key',
  },
});

// Add new remote type definitions
client.updateGraphQLRemoteSource({
  prefix: 'External',
  remoteTypeDefinitionsToUpsert: {
    remoteTypeDefinitionsToCreate: [
      {
        sdl: `
          input NewFilterInput {
            field: String!
            value: String!
          }
        `,
      },
    ],
  },
});
```


**Enums**

- `RemoteSourceKind`: `CommerceTools`, `CommerceLayer`, `Custom`
- `GraphQLRemoteSourceIntrospectionMethod`: `GET`, `POST`
- `OAuthGrantType`: `client_credentials`

### refreshGraphQLRemoteSourceSchema()

Refreshes the schema for a GraphQL remote source.

**Use cases:**
- Updating remote schema after API changes.
- Syncing with latest remote API schema.
- Refreshing available types and fields.

**Important notes:**
- Only requires prefix to identify the remote source.
- Async operation. It may take time to complete.
- Updates available types and fields from remote schema.
- Should be called when remote API schema changes.

  **Parameters**

```ts
client.refreshGraphQLRemoteSourceSchema({
  prefix: string  // Required: Remote source prefix
})
```


  **Examples**

```ts
// Refresh schema for a GraphQL remote source
client.refreshGraphQLRemoteSourceSchema({
  prefix: 'External',
});

// Refresh schema after updating the remote API
client.refreshGraphQLRemoteSourceSchema({
  prefix: 'CommerceTools',
});
```


### createRESTRemoteSource()

Creates a new REST remote source.

**Use cases:**
- Integrating REST APIs.
- Connecting to external REST services.
- Building API integrations.

**Important notes:**
- `prefix` is immutable. It cannot be changed after creation.
- `remoteTypeDefinitions` define available types and operations.
- `OAuth` configuration is optional but required for protected APIs.

  **Parameters**

```ts
client.createRESTRemoteSource({
  displayName: string,              // Required: Display name
  prefix: string,                   // Required: Unique prefix for remote types (cannot be changed!)
  url: string,                      // Required: REST API base URL
  kind: RemoteSourceKind,           // Required: Remote source kind enum
  description?: string,              // Optional: Description
  headers?: JSON,                    // Optional: Custom headers (JSON object)
  remoteTypeDefinitions?: {         // Optional: Remote type definitions
    sdl: string                      // Required: GraphQL SDL string defining types
  },
  debugEnabled?: boolean,           // Optional: Enable debug mode
  oAuth?: {                         // Optional: OAuth configuration
    clientId: string,               // Required: OAuth client ID
    clientSecret?: string,          // Optional: OAuth client secret
    scopes?: string[],              // Optional: OAuth scopes
    authorizationGrantType: OAuthGrantType, // Required: OAuth grant type
    authorizationUrl: string        // Required: OAuth authorization URL
  }
})
```


  **Examples**

```ts
// Basic REST remote source
client.createRESTRemoteSource({
  displayName: 'External REST API',
  prefix: 'External',
  url: 'https://api.example.com',
  kind: RemoteSourceKind.Custom,
});

// REST remote source with headers
client.createRESTRemoteSource({
  displayName: 'Protected REST API',
  prefix: 'Protected',
  url: 'https://api.example.com',
  kind: RemoteSourceKind.Custom,
  headers: {
    Authorization: 'Bearer api-token',
    'X-API-Key': 'your-api-key',
  },
});

// REST remote source with OAuth
client.createRESTRemoteSource({
  displayName: 'OAuth REST API',
  prefix: 'OAuth',
  url: 'https://api.example.com',
  kind: RemoteSourceKind.Custom,
  oAuth: {
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret',
    scopes: ['read:products', 'write:products'],
    authorizationGrantType: OAuthGrantType.client_credentials,
    authorizationUrl: 'https://auth.example.com/oauth/token',
  },
});
```


**Enums**

- `RemoteSourceKind`: `CommerceTools`, `CommerceLayer`, `Custom`
- `OAuthGrantType`: `client_credentials`

### updateRESTRemoteSource()

Updates an existing REST remote source.

**Use cases:**
- Updating REST API URLs.
- Modifying OAuth configuration.
- Adding/updating remote type definitions.
- Changing authentication settings.

**Important notes:**
- `prefix` cannot be changed (immutable).
- `remoteTypeDefinitionsToUpsert` uses create/update/delete structure.
- OAuth configuration can be updated.
- URL can be changed if API endpoint changes.

  **Parameters**

```ts
client.updateRESTRemoteSource({
  prefix: string,                   // Required: Remote source prefix (used to identify the source)
  displayName: string,              // Required: New display name
  description?: string,             // Optional: New description
  url?: string,                     // Optional: New REST API base URL
  headers?: JSON,                   // Optional: Custom headers (JSON object)
  remoteTypeDefinitionsToUpsert?: { // Optional: Manage remote type definitions
    remoteTypeDefinitionsToCreate?: Array<{ // Optional: Create new type definitions
      sdl: string                    // Required: GraphQL SDL string
    }>,
    remoteTypeDefinitionsToUpdate?: Array<{ // Optional: Update existing type definitions
      apiId: string,                 // Required: Type definition API ID
      sdl?: string                   // Optional: New SDL string
    }>,
    remoteTypeDefinitionsToDelete?: Array<{ // Optional: Delete type definitions
      apiId: string                  // Required: Type definition API ID
    }>
  },
  debugEnabled?: boolean,          // Optional: Enable/disable debug mode
  kind?: RemoteSourceKind,         // Optional: Remote source kind enum
  oAuth?: {                         // Optional: OAuth configuration
    clientId: string,               // Required: OAuth client ID
    clientSecret?: string,          // Optional: OAuth client secret
    scopes?: string[],              // Optional: OAuth scopes
    authorizationGrantType: OAuthGrantType, // Required: OAuth grant type
    authorizationUrl: string        // Required: OAuth authorization URL
  }
})
```


  **Examples**

```ts
// Basic update - change display name and URL
client.updateRESTRemoteSource({
  prefix: 'External',
  displayName: 'Updated REST API',
  url: 'https://api.example.com/new-endpoint',
});

// Update headers
client.updateRESTRemoteSource({
  prefix: 'External',
  displayName: 'External REST API',
  headers: {
    Authorization: 'Bearer new-token',
    'X-API-Key': 'new-api-key',
  },
});

// Add new remote type definitions
client.updateRESTRemoteSource({
  prefix: 'External',
  displayName: 'External REST API',
  remoteTypeDefinitionsToUpsert: {
    remoteTypeDefinitionsToCreate: [
      {
        sdl: `
          type Product {
            id: ID!
            name: String!
            price: Float!
          }
        `,
      },
    ],
  },
});
```


**Enums**

- `RemoteSourceKind`: `CommerceTools`, `CommerceLayer`, `Custom`
- `OAuthGrantType`: `client_credentials`

### deleteRemoteSource()

Deletes a remote source.

**Use cases:**
- Removing unused remote sources.
- Cleaning up deprecated API integrations.
- Restructuring remote integrations.

**Important notes:**
- Permanent deletion. This action cannot be undone.
- Cannot delete if used by remote fields.
- Must delete all remote fields using the remote source first.
- Deletes all remote type definitions.

  **Parameters**

```ts
client.deleteRemoteSource({
  prefix: string  // Required: The prefix of the remote source to delete
})
```

  
  **Example**

```ts
// Delete a remote source
client.deleteRemoteSource({
  prefix: 'External',
});

console.log('Remote source deleted');
```


## Remote fields

### createRemoteField()

Creates a remote field that fetches data from a GraphQL or REST remote source.

**Use cases:**
- Fetching data from external APIs.
- Displaying remote content in Hygraph.
- Building hybrid content systems.

**Important notes:**
- Requires existing remote source (remoteSourceApiId).
- `remoteConfig` defines how to fetch data.
- `inputArgs` allow passing parameters to remote API.
- Field type determined by remote source type (GRAPHQL or REST).

  **Parameters**

```ts
client.createRemoteField({
  apiId: string,                    // Required: Field API ID
  parentApiId: string,              // Required: API ID of parent model
  type: RemoteFieldType,            // Required: GRAPHQL or REST
  displayName: string,              // Required: Display name
  description?: string,             // Optional: Description
  tableRenderer?: string,           // Optional: Table renderer identifier
  formRenderer?: string,            // Optional: Form renderer identifier
  tableExtension?: string,          // Optional: Table extension identifier
  formExtension?: string,           // Optional: Form extension identifier
  formConfig?: JSON,                // Optional: Form configuration JSON
  tableConfig?: JSON,               // Optional: Table configuration JSON
  isList?: boolean,                 // Optional: Whether field accepts multiple values (default: false)
                                    // WARNING: Converting existing fields to/from list may cause data loss
  isRequired?: boolean,             // Optional: Whether field is required (default: false)
                                    // When changing to true, provide migrationValue for existing null entries
  visibility?: VisibilityTypes,    // Optional: Visibility setting
  position?: number,                // Optional: Field position
  remoteConfig: {                   // Required: Configuration for fetching remote data
    returnTypeApiId: string,       // Required: API ID of return type defined in remote source
                                    // Must exist in the remote source's type definitions
    remoteSourcePrefix: string,    // Required: Prefix of the remote source to use
                                    // Must match prefix from createGraphQLRemoteSource or createRESTRemoteSource
    method: RemoteFieldApiMethod,   // Required: HTTP method (GET or POST)
                                    // GET for simple queries, POST for mutations or complex queries
    headers?: JSON,                 // Optional: Custom HTTP headers (JSON object)
                                    // Example: { "Authorization": "Bearer token" }
    cacheTTLSeconds?: number,       // Optional: Cache duration in seconds
                                    // 0 = no cache, default varies by remote source type
    graphQLQuery?: string,          // Required for GRAPHQL type remote fields
                                    // Complete GraphQL query string
    restPath?: string,             // Required for REST type remote fields
                                    // API endpoint path (e.g., "/users/{id}")
                                    // Can include path parameters in curly braces
    forwardClientHeaders?: boolean // Optional: Pass client request headers to remote API (default: false)
                                    // Useful for authentication/authorization
  },
  inputArgs?: Array<{              // Optional: Arguments passed to remote field query
    remoteTypeApiId: string,       // Required: API ID of input type from remote source
    apiId: string,                 // Required: Argument name (used in GraphQL query or REST path)
    isRequired: boolean,            // Required: Whether this argument must be provided
    isList: boolean                // Required: Whether argument accepts array of values
  }>
})
```


  **Examples**

```ts
// GraphQL remote field
client.createRemoteField({
  parentApiId: 'Product',
  apiId: 'externalData',
  displayName: 'External Data',
  type: RemoteFieldType.GRAPHQL,
  remoteConfig: {
    returnTypeApiId: 'ExternalProduct',
    remoteSourcePrefix: 'External',
    method: RemoteFieldApiMethod.POST,
    graphQLQuery: `
      query GetProduct($id: ID!) {
        product(id: $id) {
          id
          name
          price
        }
      }
    `,
    headers: {
      Authorization: 'Bearer token',
    },
    cacheTTLSeconds: 300,
  },
});

// REST remote field
client.createRemoteField({
  parentApiId: 'Product',
  apiId: 'externalInventory',
  displayName: 'External Inventory',
  type: RemoteFieldType.REST,
  remoteConfig: {
    returnTypeApiId: 'Inventory',
    remoteSourcePrefix: 'External',
    method: RemoteFieldApiMethod.GET,
    restPath: '/inventory/{id}',
    headers: {
      'X-API-Key': 'api-key',
    },
    forwardClientHeaders: true,
    cacheTTLSeconds: 60,
  },
});
```


**Enum**

- `RemoteFieldType`: `GRAPHQL`, `REST`
- `RemoteFieldApiMethod`: `GET`, `POST`
- `VisibilityTypes`: `READ_WRITE`, `READ_ONLY`, `HIDDEN`, `API_ONLY`

### updateRemoteField()

This example shows how to update an existing remote field.

**Use cases:**
- Updating remote field configuration.
- Changing API endpoints or methods.
- Modifying input arguments.

**Important notes:**
- `remoteConfig` can be updated.
- `inputArgs` can be modified.
- Field type cannot be changed.

  **Parameters**

```ts
client.updateRemoteField({
  apiId: string,                    // Required: Current field API ID
  parentApiId: string,              // Required: Parent model API ID
  newApiId?: string,                // Optional: New API ID (to rename the field)
  displayName?: string,             // Optional: New display name
  description?: string,             // Optional: New description
  isList?: boolean,                 // Optional: Whether field accepts multiple values (default: false)
                                    // WARNING: Converting existing fields to/from list may cause data loss
  isRequired?: boolean,             // Optional: Whether field is required
                                    // When changing to true, provide migrationValue for existing null entries
  visibility?: VisibilityTypes,    // Optional: Visibility setting
  formConfig?: JSON,                // Optional: Form configuration JSON
  tableConfig?: JSON,               // Optional: Table configuration JSON
  extensions?: JSON,                // Optional: Extensions JSON
  meta?: JSON,                      // Optional: Meta JSON
  position?: number,                // Optional: Field position
  remoteConfig?: {                  // Optional: Update remote field configuration
    returnTypeApiId?: string,       // Optional: New return type API ID
    remoteSourcePrefix?: string,    // Optional: New remote source prefix
    method?: RemoteFieldApiMethod,  // Optional: HTTP method
    headers?: JSON,                 // Optional: Custom headers
    cacheTTLSeconds?: number,       // Optional: Cache TTL in seconds
    graphQLQuery?: string,          // Optional: GraphQL query (for GRAPHQL type)
    restPath?: string,             // Optional: REST path (for REST type)
    forwardClientHeaders?: boolean // Optional: Forward client headers
  },
  inputArgs?: {                    // Optional: Update input arguments (add/remove/update structure)
    fieldInputArgsToCreate?: Array<{ // Optional: Create new input arguments
      remoteTypeApiId: string,     // Required: API ID of the remote input type
      apiId: string,                // Required: Argument API ID
      isRequired: boolean,           // Required: Whether argument is required
                                    // When changing to true, provide migrationValue for existing null entries
      isList: boolean               // Required: Whether argument is a list
    }>,
    fieldInputArgsToUpdate?: Array<{ // Optional: Update existing input arguments
      argApiId: string,             // Required: Current argument API ID
      remoteTypeApiId?: string,     // Optional: New remote type API ID
      apiId?: string,               // Optional: New argument API ID
      isRequired?: boolean,          // Optional: Whether argument is required
                                    // When changing to true, provide migrationValue for existing null entries
      isList?: boolean              // Optional: Whether argument is a list
    }>,
    fieldInputArgsToDelete?: Array<{ // Optional: Delete input arguments
      argApiId: string              // Required: Argument API ID to delete
    }>
  }
})
```

  
  **Examples**

```ts
// Basic update - rename field and change display name
client.updateRemoteField({
  apiId: 'externalData',
  parentApiId: 'Product',
  newApiId: 'externalProductData',
  displayName: 'External Product Data',
});

// Update remote config - change GraphQL query
client.updateRemoteField({
  apiId: 'externalData',
  parentApiId: 'Product',
  remoteConfig: {
    graphQLQuery: `
      query GetProduct($id: ID!) {
        product(id: $id) {
          id
          name
          price
          description
        }
      }
    `,
    cacheTTLSeconds: 600,
  },
});

// Add new input arguments
client.updateRemoteField({
  apiId: 'externalData',
  parentApiId: 'Product',
  inputArgs: {
    fieldInputArgsToCreate: [
      {
        remoteTypeApiId: 'Boolean',
        apiId: 'includeReviews',
        isRequired: false,
        isList: false,
      },
    ],
  },
});
```


**Enum**
- `RemoteFieldType`: `GRAPHQL`, `REST`
- `RemoteFieldApiMethod`: `GET`, `POST`
- `VisibilityTypes`: `READ_WRITE`, `READ_ONLY`, `HIDDEN`, `API_ONLY`

## Locales

### createLocale()

Creates a new locale (language/region) for content localization.

**Use cases:**
- Setting up multi-language content
- Adding new language support
- Configuring localization

**Important notes:**
- Locale code must follow ISO 639-1 format, such as `en`, `de`, `fr`.
- `isDefault` determines default locale
- Only one locale can be default
- Locales are environment-specific

  **Parameters**

```ts
client.createLocale({
  apiId: string,                    // Required: Locale API ID (e.g., "en", "en_US", "de")
  displayName: string,              // Required: Display name (e.g., "English", "English (US)", "German")
  description?: string              // Optional: Description
})
```


  **Examples**

```ts
// Basic locale creation
client.createLocale({
  apiId: 'en',
  displayName: 'English',
  description: 'English language',
});

// Locale with region
client.createLocale({
  apiId: 'en_US',
  displayName: 'English (US)',
  description: 'English - United States',
});

// Multiple locales
client.createLocale({
  apiId: 'de',
  displayName: 'German',
  description: 'German language',
});

client.createLocale({
  apiId: 'fr',
  displayName: 'French',
  description: 'French language',
});
```


### updateLocale()

Updates an existing locale.

**Use cases:**
- Changing default locale.
- Updating locale display names.
- Modifying locale settings.

**Important notes:**
- Changing `isDefault` to `true` sets this as default and removes default from others.
- Locale `apiId` cannot be changed.

  **Parameters**

```ts
client.updateLocale({
  apiId: string,                    // Required: Current locale API ID
  newApiId?: string,                // Optional: New API ID (to rename the locale)
  displayName?: string,             // Optional: New display name
  description?: string,             // Optional: New description
  isDefault?: boolean               // Optional: Whether this locale is the default
})
```


  **Examples**

```ts
// Basic update - rename locale and change display name
client.updateLocale({
  apiId: 'en',
  newApiId: 'en_US',
  displayName: 'English (US)',
  description: 'English - United States',
});

// Set locale as default
client.updateLocale({
  apiId: 'en',
  isDefault: true,
});

// Update only display name
client.updateLocale({
  apiId: 'de',
  displayName: 'Deutsch',
});
```


### deleteLocale()

Deletes a locale.

**Use cases:**

- Removing language support.
- Cleaning up unused locales.

**Important notes:**
- Permanent deletion. This action cannot be undone.
- Cannot delete default locale.
- May affect localized content.

  **Parameters**

```ts
client.deleteLocale({
  apiId: string,                    // Required: The API ID of the locale to delete
  force?: boolean                   // Optional: Force delete even if locale has content
})
```


  **Examples**

```ts
// Delete a locale
client.deleteLocale({
  apiId: 'de',
});

// Force delete a locale (even if it has content)
client.deleteLocale({
  apiId: 'fr',
  force: true,
});

console.log('Locale deleted');
```


## Stages

### createStage()

Creates a new content stage, such as `Draft`, `Published`, `Archived`.

**Use cases:**

- Setting up content publishing stages (`Draft`, `Published`, `Archived`).
- Creating content lifecycle stages.
- Building stage-based content workflows.

**Important notes:**
- Stage `apiId` typically `UPPERCASE`, such as, `DRAFT`, `PUBLISHED`.
- `color` uses `ColorPalette` enum.
- Stages are environment-specific.
- `position` determines display order.

  **Parameters**

```ts
client.createStage({
  apiId: string,                    // Required: Stage API ID (e.g., "DRAFT", "PUBLISHED", "ARCHIVED")
  displayName: string,              // Required: Display name (e.g., "Draft", "Published", "Archived")
  color: ColorPalette,              // Required: Stage color enum
  description?: string,             // Optional: Description
  position?: number                 // Optional: Stage position (for ordering)
})
```


  **Examples**

```ts
// Basic stage creation
client.createStage({
  apiId: 'DRAFT',
  displayName: 'Draft',
  color: ColorPalette.BLUE,
  description: 'Work in progress',
});

// Published stage
client.createStage({
  apiId: 'PUBLISHED',
  displayName: 'Published',
  color: ColorPalette.GREEN,
  description: 'Published content',
});

// Stage with position
client.createStage({
  apiId: 'REVIEW',
  displayName: 'In Review',
  color: ColorPalette.YELLOW,
  description: 'Awaiting review',
  position: 1,
});
```


**Enum**

- `ColorPalette`: `PURPLE`, `TEAL`, `YELLOW`, `GREEN`, `BLUE`, `RED`, `PINK`, `BROWN`, `ORANGE`, `INDIGO`, `OLIVE`, `ROSE`, `NEUTRAL`

### updateStage()

Updates an existing content stage.

**Use cases:**
- Renaming stages.
- Changing stage colors.
- Updating stage descriptions.
- Reordering stages.

**Important notes:**
- Uses `display` (not `displayName`) for display name.
- Can change color for visual distinction.
- `position` controls ordering.

  **Parameters**

```ts
client.updateStage({
  apiId: string,                    // Required: Current stage API ID
  newApiId?: string,                // Optional: New API ID (to rename the stage)
  display?: string,                 // Optional: New display name
  description?: string,             // Optional: New description
  color?: ColorPalette,            // Optional: New stage color enum
  position?: number                 // Optional: New stage position
})
```


  **Examples**

```ts
// Basic update - rename stage and change display name
client.updateStage({
  apiId: 'DRAFT',
  newApiId: 'DRAFT_STAGE',
  display: 'Draft Stage',
  description: 'Work in progress',
});

// Update color
client.updateStage({
  apiId: 'DRAFT',
  color: ColorPalette.BLUE,
});

// Update display name
client.updateStage({
  apiId: 'PUBLISHED',
  display: 'Published Content',
});

// Update position
client.updateStage({
  apiId: 'REVIEW',
  position: 1,
});
```


**Enum**

- `ColorPalette`: `PURPLE`, `TEAL`, `YELLOW`, `GREEN`, `BLUE`, `RED`, `PINK`, `BROWN`, `ORANGE`, `INDIGO`, `OLIVE`, `ROSE`, `NEUTRAL`

### deleteStage()

Deletes a content stage.

**Use cases:**
- Removing unused stages.
- Cleaning up test stages.

**Important notes:**
- Permanent deletion. This action cannot be undone.
- Cannot delete if used by entries.
- May affect published content.

  **Parameters**

```ts
client.deleteStage({
  apiId: string,                    // Required: The API ID of the stage to delete
})
```

  
  **Example**

```ts
// Delete a stage
client.deleteStage({
  apiId: 'ARCHIVED',
});

console.log('Stage deleted');
```


## Taxonomies

Taxonomies organize content into hierarchical categories.

### createTaxonomy()

Creates a taxonomy with hierarchical nodes.

**Use cases:**
- Creating hierarchical category systems.
- Building tag hierarchies.
- Setting up nested classification systems.

**Important notes:**
- Can create with either `rootNode` OR `taxonomyNodes`.
- `rootNode` approach: provides root node, children become taxonomy nodes.
- `taxonomyNodes` approach: provides all nodes, root has parent: null.
- Taxonomy `apiId` must be PascalCase and unique.

  **Parameters**

```ts
// Approach 1: Hierarchical structure (easier to read)
client.createTaxonomy({
  apiId: string,                    // Required: Taxonomy API ID
  displayName: string,              // Required: Display name
  description?: string,             // Optional: Description
  rootNode?: {                      // Optional: Root node with children (mutually exclusive with taxonomyNodes)
    apiId: string,                  // Required: Root node API ID
    displayName: string,            // Required: Root node display name
    children?: Array<{              // Optional: Child nodes (recursive structure)
      apiId: string,                // Required: Child node API ID
      displayName: string,           // Required: Child node display name
      children?: Array<...>         // Optional: Nested children (recursive)
    }>
  },
})

// Approach 2: Flat array (easier for programmatic generation)

client.createTaxonomy({
  apiId: string,                    // Required: Taxonomy API ID
  displayName: string,              // Required: Display name
  description?: string,             // Optional: Description
  taxonomyNodes?: Array<{          // Optional: Flat array of nodes (mutually exclusive with rootNode)
    apiId: string,                  // Required: Node API ID
    displayName: string,           // Required: Node display name
    parent?: string                 // Optional: Parent node API ID (null for root node)
  }>
})
```

  
  **Examples**

```ts
// Basic taxonomy with rootNode (nested structure)
client.createTaxonomy({
  apiId: 'BlogCategories',
  displayName: 'Blog Categories',
  description: 'Hierarchical blog categorization',
  rootNode: {
    apiId: 'technology',
    displayName: 'Technology',
    children: [
      {
        apiId: 'webDev',
        displayName: 'Web Development',
        children: [
          { apiId: 'react', displayName: 'React' },
          { apiId: 'vue', displayName: 'Vue.js' },
        ],
      },
    ],
  },
});

// Taxonomy with flat taxonomyNodes array
client.createTaxonomy({
  apiId: 'BlogCategories',
  displayName: 'Blog Categories',
  taxonomyNodes: [
    { apiId: 'technology', displayName: 'Technology', parent: null },
    { apiId: 'webDev', displayName: 'Web Development', parent: 'technology' },
  ],
});
```


### updateTaxonomy()

Updates metadata of an existing taxonomy. Nodes are managed separately.

**Use cases:**
- Renaming taxonomies.
- Updating taxonomy descriptions.
- Changing taxonomy display names.

**Important notes:**
- Can change `displayName` and `description`.
- Cannot change `apiId` directly (use `newApiId`).
- Renaming updates all references to the taxonomy.

  **Parameters**

```ts
// Update a taxonomy
client.updateTaxonomy({
  apiId: string,                    // Required: Current taxonomy API ID
  newApiId?: string,                // Optional: New API ID (to rename the taxonomy)
  displayName?: string,             // Optional: New display name
  description?: string              // Optional: New description
})
```

  
  **Examples**

```ts
  // Basic update - rename taxonomy and change display name
client.updateTaxonomy({
  apiId: 'BlogCategories',
  newApiId: 'ArticleCategories',
  displayName: 'Article Categories',
  description: 'Updated categorization system',
});

// Update only display name
client.updateTaxonomy({
  apiId: 'BlogCategories',
  displayName: 'Content Categories',
});
```


### deleteTaxonomy()

Deletes a taxonomy and all its nodes. You cannot delete a taxonomy if any fields reference it.

**Use cases:**
- Removing unused taxonomies.
- Cleaning up deprecated category systems.
- Restructuring classification systems.

**Important notes:**
- Permanent deletion. This action cannot be undone.
- Deletes all taxonomy nodes.
- Cannot delete if used by taxonomy fields.
- Must delete all taxonomy fields using the taxonomy first.

  **Parameters**

```ts
client.deleteTaxonomy({
  apiId: string  // Required: The API ID of the taxonomy to delete
})
```

  
  **Example**

```ts
// Delete a taxonomy
client.deleteTaxonomy({
  apiId: 'BlogCategories',
});

console.log('Taxonomy deleted');
```


### createTaxonomyNode()

Adds a new node to an existing taxonomy.

**Use cases:**
- Adding categories to existing taxonomies.
- Building nested category structures.
- Expanding taxonomy hierarchies.

**Important notes:**
- `parentApiId: null` creates a root-level node.
- `parentApiId` references another taxonomy node's apiId.
- Nodes can be nested to any depth.

  **Parameters**

```ts
client.createTaxonomyNode({
  taxonomyApiId: string,            // Required: API ID of the taxonomy
  apiId: string,                    // Required: Node API ID
  displayName: string,              // Required: Node display name
  parent?: string,                  // Optional: Parent node API ID (null or omit for root node)
  children?: Array<{                // Optional: Child nodes (nested structure)
    apiId: string,                  // Required: Child node API ID
    displayName: string,            // Required: Child node display name
    children?: Array<...>           // Optional: Nested children (recursive)
  }>
})
```

  
  **Examples**

```ts
// Create a root node (no parent)
client.createTaxonomyNode({
  taxonomyApiId: 'BlogCategories',
  apiId: 'technology',
  displayName: 'Technology',
});

// Create a child node
client.createTaxonomyNode({
  taxonomyApiId: 'BlogCategories',
  apiId: 'webDev',
  displayName: 'Web Development',
  parent: 'technology', // Parent node API ID
});

// Create a node with nested children
client.createTaxonomyNode({
  taxonomyApiId: 'BlogCategories',
  apiId: 'technology',
  displayName: 'Technology',
  parent: null, // Root node
  children: [
    {
      apiId: 'webDev',
      displayName: 'Web Development',
      children: [
        { apiId: 'react', displayName: 'React' },
        { apiId: 'vue', displayName: 'Vue.js' },
      ],
    },
  ],
});
```


### updateTaxonomyNode()

Updates an existing taxonomy node.

**Use cases:**
- Moving taxonomy nodes (changing parent).
- Renaming taxonomy nodes.
- Updating node descriptions.
- Reorganizing taxonomy hierarchy.

**Important notes:**
- `parent` parameter changes the node's parent (can move nodes).
- Set `parent: null` to make a node root-level.
- Can change `apiId` using `newApiId`.
- Moving nodes updates the entire hierarchy.

  **Parameters**

```ts
client.updateTaxonomyNode({
  taxonomyApiId: string,            // Required: API ID of the taxonomy
  apiId: string,                    // Required: Current node API ID
  newApiId?: string,                // Optional: New API ID (to rename the node)
  displayName?: string,             // Optional: New display name
  parent?: string | null            // Optional: New parent node API ID (null for root node)
})
```


  **Examples**

```ts
// Basic update - rename node and change display name
client.updateTaxonomyNode({
  taxonomyApiId: 'BlogCategories',
  apiId: 'webDev',
  newApiId: 'webDevelopment',
  displayName: 'Web Development',
});

// Move node to different parent
client.updateTaxonomyNode({
  taxonomyApiId: 'BlogCategories',
  apiId: 'react',
  parent: 'frontend', // Move 'react' under 'frontend' node
});

// Move node to root (make it a root node)
client.updateTaxonomyNode({
  taxonomyApiId: 'BlogCategories',
  apiId: 'technology',
  parent: null, // Make it a root node
});
```


### deleteTaxonomyNode()

Deletes a taxonomy node and all its children.

**Use cases:**
- Removing unused taxonomy nodes.
- Cleaning up deprecated categories.
- Simplifying taxonomy hierarchies.

**Important notes:**
- Permanent deletion. This action cannot be undone.
- Deletes the node and all its children (cascading deletion).
- Cannot delete if used by taxonomy fields.
- Must update or delete taxonomy fields using the node first.

  **Parameters**

```ts
client.deleteTaxonomyNode({
  taxonomyApiId: string,            // Required: API ID of the taxonomy
  apiId: string                      // Required: API ID of the node to delete
})
```


  **Example**

```ts
// Delete a taxonomy node
client.deleteTaxonomyNode({
  taxonomyApiId: 'BlogCategories',
  apiId: 'webDev',
});

console.log('Taxonomy node deleted');
```


### createTaxonomyField()

Creates a taxonomy field that links a model to a taxonomy.

**Use cases:**
- Linking models to taxonomies.
- Adding category/tag fields to content.
- Creating classification systems.

**Important notes:**
- `initialValue` and `migrationValue` must be JSON stringified.
- Single value: `JSON.stringify('nodeApiId')`.
- List value: `JSON.stringify(['node1', 'node2'])`.
- Cannot use `isUnique` with `initialValue` or `migrationValue`.
- `migrationValue` is used for existing data, `initialValue` for new entries.

  **Parameters**

```ts
client.createTaxonomyField({
  apiId: string,                    // Required: Field API ID
  parentApiId: string,              // Required: API ID of parent model
  taxonomyApiId: string,            // Required: API ID of the taxonomy to link to
  displayName: string,              // Required: Display name
  description?: string,             // Optional: Description
  isVariantEnabled?: boolean,       // Optional: Enable variant support
  isList?: boolean,                 // Optional: Whether field accepts multiple values (default: false)
                                    // WARNING: Converting existing fields to/from list may cause data loss
  isRequired?: boolean,             // Optional: Whether field is required (default: false)
                                    // When changing to true, provide migrationValue for existing null entries
  isUnique?: boolean,               // Optional: Whether field is unique (default: false)
                                    // CANNOT be used with initialValue or migrationValue
  initialValue?: string,            // Optional: JSON stringified initial value (for new entries)
                                    // If isList is true, this should be a JSON stringified array of apiIds
                                    // If isList is false, this should be a JSON stringified apiId
  migrationValue?: string,          // Optional: JSON stringified taxonomy node API ID for initial value
  visibility?: VisibilityTypes,    // Optional: Visibility setting
  position?: number,                // Optional: Field position
  visibilityCondition?: {           // Optional: Show/hide field based on another field's value
    baseField: string,              // Required: API ID of the field that controls visibility
    operator: FieldConditionOperator, // Required: Comparison operator (IS, IS_NOT, etc.)
    enumerationValues?: string[],   // Required when baseField is enumeration type
    booleanValue?: boolean          // Required when baseField is boolean type
  },
  isSystem?: boolean                // Optional: System field flag (only for AppTokens)
})
```


  **Examples**

```ts
// Basic taxonomy field - single selection
client.createTaxonomyField({
  parentApiId: 'Post',
  apiId: 'category',
  displayName: 'Category',
  taxonomyApiId: 'BlogCategories',
  isRequired: false,
});

// Taxonomy field with list support (multiple selections)
client.createTaxonomyField({
  parentApiId: 'Post',
  apiId: 'categories',
  displayName: 'Categories',
  taxonomyApiId: 'BlogCategories',
  isList: true,
  isRequired: false,
});

// Taxonomy field with initial value
client.createTaxonomyField({
  parentApiId: 'Post',
  apiId: 'category',
  displayName: 'Category',
  taxonomyApiId: 'BlogCategories',
  initialValue: JSON.stringify('technology'), // JSON stringified taxonomy node API ID
});
```


**Enums**

- `VisibilityTypes`: `READ_WRITE`, `READ_ONLY`, `HIDDEN`, `API_ONLY`
- `FieldConditionOperator`: `IS`, `IS_NOT`, `CONTAINS_ANY`, `CONTAINS_ALL`, `CONTAINS_NONE`

### updateTaxonomyField()

Updates an existing taxonomy field.

**Use cases:**
- Renaming taxonomy fields.
- Updating field visibility.
- Changing required/unique status.
- Updating initial/migration values.
- Adding conditional visibility.
- Changing taxonomy reference.

**Important notes:**
- `initialValue` and `migrationValue` must be JSON stringified.
- Single value: `JSON.stringify('nodeApiId')`.
- List value: `JSON.stringify(['node1', 'node2'])`.
- Cannot use `isUnique` with `initialValue` or `migrationValue`.
- When changing `isRequired` to `true`, provide `migrationValue` for existing null entries.
- Cannot change `isList` without potential data loss.
- `visibilityCondition` can be set to `null` to remove it.
- Cannot change `taxonomyApiId`. Taxonomy reference is immutable.

  **Parameters**

```ts
client.updateTaxonomyField({
  apiId: string,                    // Required: Current field API ID
  newApiId?: string,                // Optional: New API ID (to rename the field)
  parentApiId?: string,             // Optional: Parent model API ID
  displayName?: string,             // Optional: New display name
  description?: string,             // Optional: New description
  isVariantEnabled?: boolean,       // Optional: Enable/disable variant support
  isRequired?: boolean,             // Optional: Whether field is required
                                    // When changing to true, provide migrationValue for existing null entries
  isUnique?: boolean,               // Optional: Whether field is unique
                                    // CANNOT be used with initialValue or migrationValue
  visibility?: VisibilityTypes,    // Optional: Visibility setting
  position?: number,                // Optional: Field position
  initialValue?: string,            // Optional: JSON stringified initial value (for new entries)
  migrationValue?: string,          // Optional: JSON stringified taxonomy node API ID (for existing data)
  visibilityCondition?: {           // Optional: Show/hide field based on another field's value
    baseField: string,              // Required: API ID of the field that controls visibility
    operator: FieldConditionOperator, // Required: Comparison operator (IS, IS_NOT, etc.)
    enumerationValues?: string[],   // Required when baseField is enumeration type
    booleanValue?: boolean          // Required when baseField is boolean type
  },
  isSystem?: boolean                // Optional: System field flag (only for AppTokens)
})
```


  **Examples**

```ts
// Basic update - rename field and change display name
client.updateTaxonomyField({
  apiId: 'category',
  parentApiId: 'Post',
  newApiId: 'primaryCategory',
  displayName: 'Primary Category',
});

// Update initial value
client.updateTaxonomyField({
  apiId: 'category',
  parentApiId: 'Post',
  initialValue: JSON.stringify('technology'), // Single value
});

// Update initial value for list field
client.updateTaxonomyField({
  apiId: 'categories',
  parentApiId: 'Post',
  initialValue: JSON.stringify(['technology', 'business']), // Array
});
```


**Enums**

- `VisibilityTypes`: `READ_WRITE`, `READ_ONLY`, `HIDDEN`, `API_ONLY`
- `FieldConditionOperator`: `IS`, `IS_NOT`, `CONTAINS_ANY`, `CONTAINS_ALL`, `CONTAINS_NONE`

## Workflows

### createWorkflow()

**Use cases:**
- Setting up content approval processes.
- Creating editorial workflows.
- Building multi-step content review systems.

**Important notes:**
- Steps are created in the order provided unless position is specified. If a position conflicts, the new step is inserted at the next available position.
- First step cannot have `returnToStep`.
- `roleOverrides` at workflow level bypasses all steps.
- `allowedRoles` at step level controls who can work at that step.
- `publishStages` determines which stages can be published from a step.
- Steps with conflicting positions are inserted at next available slot.

  **Parameters**

```ts
client.createWorkflow({
  apiId: string,                    // Required: Workflow API ID
  displayName: string,             // Required: Display name
  description?: string,             // Optional: Description
  enabled: boolean,                 // Required: Whether workflow is enabled
  modelApiIds?: string[],          // Optional: Array of model API IDs to apply workflow to
roleOverrides?: string[],        // Optional: Roles that can bypass workflow entirely
                                  // Different from step-level allowedRoles
                                  // Users with these roles can skip all workflow steps
steps: Array<{                   // Optional: Workflow steps (created in order provided)
  apiId: string,                  // Required: Step API ID (unique within workflow)
  displayName: string,            // Required: Step display name shown in UI
  description?: string,           // Optional: Step description
  color: ColorPalette,           // Required: Step color (visual indicator in UI)
  allowEdit: boolean,             // Required: Whether entries can be edited at this step
  returnToStep?: string,         // Optional: Previous step to return to
                                  // CANNOT be set for first step!
                                  // Must reference existing step API ID
  position?: number,              // Optional: Step order (0-based index)
                                  // If omitted, steps created in array order
                                  // If position conflicts, inserted at next available slot
  allowedRoles: string[],        // Required: Roles that can work at THIS specific step
                                  // Different from workflow-level roleOverrides
  publishStages?: string[]       // Optional: Stages that can be published from this step
                                  // Empty array or omitted = no publishing from this step
}>
})
```


  **Example**

```ts
// Basic workflow with steps
client.createWorkflow({
  apiId: 'editorialWorkflow',
  displayName: 'Editorial Workflow',
  description: 'Content review and approval process',
  enabled: true,
  modelApiIds: ['Post', 'Page'],
  steps: [
    {
      apiId: 'draft',
      displayName: 'Draft',
      description: 'Work in progress',
      color: ColorPalette.BLUE,
      allowEdit: true,
      allowedRoles: ['editor', 'author'],
    },
    {
      apiId: 'review',
      displayName: 'In Review',
      description: 'Awaiting editorial review',
      color: ColorPalette.YELLOW,
      allowEdit: false,
      allowedRoles: ['editor'],
      returnToStep: 'draft',
    },
    {
      apiId: 'approved',
      displayName: 'Approved',
      description: 'Ready for publication',
      color: ColorPalette.GREEN,
      allowEdit: false,
      allowedRoles: ['editor', 'admin'],
      publishStages: ['PUBLISHED'],
    },
  ],
});
```


**Enum**
- `ColorPalette`: `PURPLE`, `TEAL`, `YELLOW`, `GREEN`, `BLUE`, `RED`, `PINK`, `BROWN`, `ORANGE`, `INDIGO`, `OLIVE`, `ROSE`, `NEUTRAL`

### updateWorkflow()

Updates an existing workflow.

**Use cases:**
- Adding/removing steps.
- Updating step configurations.
- Changing workflow models or roles.
- Modifying step order.

**Important notes:**
- `modelApiIds` uses add/remove structure.
- `roleOverrides` uses add/remove structure.
- `steps` has create/update/delete structure.
- Step `allowedRoles` uses add/remove structure
- Step `publishStages` uses add/remove structure.

  **Parameters**

```ts
client.updateWorkflow({
  apiId: string,                    // Required: Current workflow API ID
  newApiId?: string,                // Optional: New API ID (to rename the workflow)
  displayName?: string,             // Optional: New display name
  description?: string,             // Optional: New description
  enabled?: boolean,                // Optional: Whether workflow is enabled
  modelApiIds?: {                   // Optional: Update models (add/remove structure)
    modelsToAdd?: string[],         // Optional: Model API IDs to add
    modelsToRemove?: string[]        // Optional: Model API IDs to remove
  },
  roleOverrides?: {                 // Optional: Update role overrides (add/remove structure)
    rolesToAdd?: string[],          // Optional: Role IDs to add
    rolesToRemove?: string[]        // Optional: Role IDs to remove
  },
  steps?: {                         // Optional: Update workflow steps
    stepsToCreate?: Array<{         // Optional: New steps to add
      apiId: string,                // Required: Step API ID
      displayName: string,          // Required: Step display name
      description?: string,         // Optional: Step description
      color: ColorPalette,          // Required: Step color
      allowEdit: boolean,           // Required: Whether entries can be edited
      returnToStep?: string,       // Optional: Step API ID to return to
      position?: number,            // Optional: Step position
      allowedRoles: string[],       // Required: Array of role IDs
      publishStages?: string[]      // Optional: Array of stage API IDs
    }>,
    stepsToUpdate?: Array<{         // Optional: Existing steps to update
      apiId: string,                // Required: Current step API ID
      displayName?: string,         // Optional: New display name
      description?: string,         // Optional: New description
      color?: ColorPalette,         // Optional: New color
      allowEdit?: boolean,          // Optional: Whether entries can be edited
      returnToStep?: string,        // Optional: Step API ID to return to
      position?: number,            // Optional: New position
      allowedRoles?: {              // Optional: Update allowed roles (add/remove structure)
        rolesToAdd?: string[],      // Optional: Role IDs to add
        rolesToRemove?: string[]    // Optional: Role IDs to remove
      },
      publishStages?: {             // Optional: Update publish stages (add/remove structure)
        stagesToAdd?: string[],     // Optional: Stage API IDs to add
        stagesToRemove?: string[]   // Optional: Stage API IDs to remove
      }
    }>,
    stepsToDelete?: string[]        // Optional: Array of step API IDs to delete
  }
})
```


  **Examples**

```ts
// Basic update - rename workflow and change display name
client.updateWorkflow({
  apiId: 'editorialWorkflow',
  newApiId: 'contentWorkflow',
  displayName: 'Content Workflow',
  description: 'Updated workflow description',
});

// Update models (add/remove)
client.updateWorkflow({
  apiId: 'editorialWorkflow',
  modelApiIds: {
    modelsToAdd: ['Page', 'Article'],
    modelsToRemove: ['Post'],
  },
});

// Add new step
client.updateWorkflow({
  apiId: 'editorialWorkflow',
  steps: {
    stepsToCreate: [
      {
        apiId: 'archived',
        displayName: 'Archived',
        color: ColorPalette.NEUTRAL,
        allowEdit: false,
        allowedRoles: ['admin'],
      },
    ],
  },
});

// Update existing step
client.updateWorkflow({
  apiId: 'editorialWorkflow',
  steps: {
    stepsToUpdate: [
      {
        apiId: 'review',
        displayName: 'In Review',
        color: ColorPalette.ORANGE,
        allowEdit: false,
      },
    ],
  },
});
```


**Enum**
- `ColorPalette`: `PURPLE`, `TEAL`, `YELLOW`, `GREEN`, `BLUE`, `RED`, `PINK`, `BROWN`, `ORANGE`, `INDIGO`, `OLIVE`, `ROSE`, `NEUTRAL`

### deleteWorkflow()

Deletes a workflow and all its steps. Models using this workflow revert to the default workflow.

** Use cases:**
- Removing unused workflows.
- Cleaning up test workflows.
- Restructuring workflow systems.

**Important notes:**
- Permanent deletion. This action cannot be undone.
- Deletes all workflow steps.
- May affect entries currently in workflow.
- Consider disabling workflow first before deletion.

  **Parameters**

```ts
client.deleteWorkflow({
  apiId: string  // Required: The API ID of the workflow to delete
})
```


  **Example**

```ts
// Delete a workflow
client.deleteWorkflow({
  apiId: 'editorialWorkflow',
});

console.log('Workflow deleted');
```


## Webhooks

### createWebhook()

Creates a webhook.

**Use cases:**
- Notifying external systems of content changes.
- Integrating with third-party services.
- Building event-driven architectures.
- Syncing content to external databases.

**Important notes:**
- `models` and `stages` are arrays of UUIDs (not API IDs).
- Empty arrays (`[]`) mean "all models/stages" including future ones.
- `triggerActions` determines which operations trigger the webhook.
- `triggerSources` filters by source (PAT, MEMBER, PUBLIC).
- `webhookId` is a UUID, not an API ID.

  **Parameters**

```ts
client.createWebhook({
  name: string,                     // Required: Webhook name
  url: string,                      // Required: Webhook URL
  isActive: boolean,                // Required: Whether webhook is active
  includePayload: boolean,          // Required: Whether to include payload in request
  models: string[],                 // Required: Array of model IDs (UUIDs) - empty array for all models
  stages: string[],                 // Required: Array of stage IDs (UUIDs) - empty array for all stages
  triggerType: WebhookTriggerType,  // Required: Trigger type enum
  triggerActions: WebhookTriggerAction[], // Required: Array of trigger action enums
  description?: string,              // Optional: Description
  method?: WebhookMethod,           // Optional: HTTP method (default: POST)
  headers?: JSON,                   // Optional: Custom headers (JSON object)
  secretKey?: string,               // Optional: Secret key for webhook signature
  triggerSources?: WebhookTriggerSource[], // Optional: Array of trigger source enums
  isSystem?: boolean                // Optional: System webhook flag (only for AppTokens)
})
```


  **Examples**

```ts
// Basic webhook - notify on publish
client.createWebhook({
  name: 'Post Publish Notification',
  description: 'Notify marketing system when blog posts are published',
  url: 'https://api.marketing.example.com/webhooks/blog-published',
  method: WebhookMethod.POST,
  headers: {
    Authorization: 'Bearer webhook-secret-token',
    'Content-Type': 'application/json',
  },
  isActive: true,
  includePayload: true,
  models: ['post-model-uuid'], // Model ID (UUID), not API ID
  stages: ['published-stage-uuid'], // Stage ID (UUID), not API ID
  triggerType: WebhookTriggerType.CONTENT_MODEL,
  triggerActions: [WebhookTriggerAction.PUBLISH],
});

// Webhook for all models and stages
client.createWebhook({
  name: 'All Content Changes',
  url: 'https://api.example.com/webhooks/all-changes',
  method: WebhookMethod.POST,
  isActive: true,
  includePayload: true,
  models: [], // Empty array = all models (including future ones)
  stages: [], // Empty array = all stages (including future ones)
  triggerType: WebhookTriggerType.CONTENT_MODEL,
  triggerActions: [
    WebhookTriggerAction.CREATE,
    WebhookTriggerAction.UPDATE,
    WebhookTriggerAction.DELETE,
  ],
});
```


**Enums**

- `WebhookMethod`: `GET`, `POST`, `PUT`, `DELETE`
- `WebhookTriggerType`: `CONTENT_MODEL`
- `WebhookTriggerAction`: `CREATE`, `UPDATE`, `DELETE`, `PUBLISH`, `UNPUBLISH`, `TRANSITION_STEP`
- `WebhookTriggerSource`: `PAT`, `MEMBER`, `PUBLIC`

### updateWebhook()

Updates an existing webhook.

**Use cases:**
- Updating webhook URLs.
- Changing trigger conditions.
- Modifying models/stages webhook applies to.

**Important notes:**
- `models`, `stages`, `triggerActions`, `triggerSources` replace entire lists.
- `webhookId` is a UUID (not API ID).
- To add or remove items, provide a complete new list.

  **Parameters**

```ts
client.updateWebhook({
  webhookId: string,                // Required: Webhook ID (UUID)
  name?: string,                     // Optional: New webhook name
  description?: string,              // Optional: New description
  url?: string,                      // Optional: New webhook URL
  method?: WebhookMethod,           // Optional: HTTP method
  headers?: JSON,                    // Optional: Custom headers (JSON object)
  isActive?: boolean,               // Optional: Whether webhook is active
  includePayload?: boolean,          // Optional: Whether to include payload
  models?: string[],                // Optional: Array of model IDs (UUIDs) - replaces entire list
  stages?: string[],                // Optional: Array of stage IDs (UUIDs) - replaces entire list
  triggerType?: WebhookTriggerType, // Optional: Trigger type enum
  triggerActions?: WebhookTriggerAction[], // Optional: Array of trigger action enums (replaces entire list)
  secretKey?: string,               // Optional: Secret key for webhook signature
  triggerSources?: WebhookTriggerSource[], // Optional: Array of trigger source enums (replaces entire list)
  isSystem?: boolean                // Optional: System webhook flag (only for AppTokens)
})
```


  **Examples**

```ts
// Basic update - change name and URL
client.updateWebhook({
  webhookId: 'webhook-uuid-here',
  name: 'Updated Webhook Name',
  url: 'https://api.example.com/webhooks/updated',
});

// Update models and stages (replaces entire list)
client.updateWebhook({
  webhookId: 'webhook-uuid-here',
  models: ['post-model-uuid', 'page-model-uuid'], // Replaces all models
  stages: ['published-stage-uuid'], // Replaces all stages
});

// Update trigger actions (replaces entire list)
client.updateWebhook({
  webhookId: 'webhook-uuid-here',
  triggerActions: [
    WebhookTriggerAction.CREATE,
    WebhookTriggerAction.UPDATE,
    WebhookTriggerAction.DELETE,
  ],
});
```


**Enums**

- `WebhookMethod`: `GET`, `POST`, `PUT`, `DELETE`
- `WebhookTriggerType`: `CONTENT_MODEL`
- `WebhookTriggerAction`: `CREATE`, `UPDATE`, `DELETE`, `PUBLISH`, `UNPUBLISH`, `TRANSITION_STEP`
- `WebhookTriggerSource`: `PAT`, `MEMBER`, `PUBLIC`

### deleteWebhook()

Deletes a webhook.

**Use cases:**
- Removing unused webhooks.
- Cleaning up test webhooks.

**Important notes:**
- Uses `webhookId` (UUID), not API ID.
- Permanent deletion. This action cannot be undone.
- Cannot delete if used by enumerable fields.
- Must delete all enumerable fields using the enumeration first.

  **Parameters**

```ts
client.deleteWebhook({
  webhookId: string  // Required: The webhook ID (UUID)
})
```

  
  **Example**

```ts
// Delete a webhook
client.deleteWebhook({
  webhookId: 'webhook-uuid-here',
});

console.log('Webhook deleted');
```


## Sidebar elements

### createCustomSidebarElement()

Creates app-based custom sidebar element.

**Use cases:**
- Adding app integrations to models.
- Creating custom UI elements.
- Integrating third-party tools.

**Important notes:**
- Requires `appApiId` and `appElementApiId`.
- `modelApiId` specifies which model to add element to
- `position` determines order (not available in standalone method, use updateModel instead).
- `config` allows passing JSON metadata.

  **Parameters**

```ts
client.createCustomSidebarElement({
  modelApiId: string,               // Required: API ID of the model
  displayName: string,              // Required: Display name for the sidebar element
  appElementApiId: string,          // Required: API ID of the App element
  appApiId: string,                 // Required: API ID of the App
  description?: string,             // Optional: Description for the sidebar element
  config?: JSON                     // Optional: JSON metadata associated with the sidebar element
})
```


  **Examples**

```ts
// Basic custom sidebar element creation
client.createCustomSidebarElement({
  modelApiId: 'Product',
  displayName: 'Product Analytics',
  description: 'View product analytics',
  appElementApiId: 'analytics-dashboard',
  appApiId: 'analytics-app',
  config: {
    refreshInterval: 30,
    showChart: true,
  },
});

// Custom sidebar element with minimal config
client.createCustomSidebarElement({
  modelApiId: 'Post',
  displayName: 'SEO Preview',
  appElementApiId: 'seo-preview',
  appApiId: 'seo-app',
});
```


### deleteCustomSidebarElement()

Deletes custom sidebar element.

**Use cases:**
- Removing app integrations.
- Cleaning up unused sidebar elements.

**Important notes:**
- Requires `appApiId`, `appElementApiId`, and `modelApiId`.
- Permanent deletion. This action cannot be undone.

  **Parameters**

```ts
client.deleteCustomSidebarElement({
  modelApiId: string,               // Required: API ID of the model
  appApiId: string,                 // Required: API ID of the App
  appElementApiId: string           // Required: API ID of the App element
})
```


  **Example**

```ts
// Delete a custom sidebar element
client.deleteCustomSidebarElement({
  modelApiId: 'Product',
  appApiId: 'analytics-app',
  appElementApiId: 'analytics-dashboard',
});

console.log('Custom sidebar element deleted');
```


### Manage sidebar elements with updateModel()

Use the `updateModel` method on the client to manage sidebar elements.

**Use cases:**
- Bulk management of sidebar elements
- Setting positions for sidebar elements
- Managing both custom and system sidebar elements

**Important notes:**
- More powerful than standalone methods.
- Allows setting position for elements.
- Can create, update, and delete in single operation.
- System sidebar elements: `INFORMATION`, `STAGES`, `LOCALIZATIONS`, `VERSIONS`, `PREVIEW_URLS`, `RELEASES`, `CONTENT_WORKFLOWS`, `VARIANTS`.

  **Parameters**

```ts
client.updateModel({
  apiId: string,                    // Required: Current model API ID
  sidebarElementsToUpsert?: {       // Optional: Sidebar elements to create/update/delete
    customSidebarElementsToCreate?: Array<{
      displayName: string,           // Required: Display name
      description?: string,          // Optional: Description
      config?: JSON,                 // Optional: JSON metadata
      appElementApiId: string,       // Required: API ID of the App element
      appApiId: string,              // Required: API ID of the App
      position?: number              // Optional: Position
    }>,
    systemSidebarElementsToCreate?: Array<{
      type: SystemSidebarElementType, // Required: System sidebar element type
      config?: JSON,                 // Optional: JSON metadata
      position?: number              // Optional: Position
    }>,
    sidebarElementsToUpdate?: Array<{
      displayName: string,           // Required: Current display name (identifier)
      newDisplayName?: string,       // Optional: New display name
      description?: string,          // Optional: New description
      config?: JSON,                 // Optional: New config
      position?: number              // Optional: New position
    }>,
    customSidebarElementsToDelete?: Array<{
      appApiId: string,              // Required: API ID of the App
      appElementApiId: string        // Required: API ID of the App element
    }>,
    systemSidebarElementsToDelete?: Array<{
      type: SystemSidebarElementType // Required: System sidebar element type
    }>
  }
})
```


  **Examples**

```ts
// Add custom sidebar elements
client.updateModel({
  apiId: 'Product',
  sidebarElementsToUpsert: {
    customSidebarElementsToCreate: [
      {
        displayName: 'Product Analytics',
        description: 'View product analytics',
        appElementApiId: 'analytics-dashboard',
        appApiId: 'analytics-app',
        position: 0,
        config: { refreshInterval: 30 },
      },
    ],
  },
});

// Add system sidebar elements
client.updateModel({
  apiId: 'Post',
  sidebarElementsToUpsert: {
    systemSidebarElementsToCreate: [
      {
        type: SystemSidebarElementType.INFORMATION,
        position: 1,
      },
      {
        type: SystemSidebarElementType.STAGES,
        position: 2,
      },
    ],
  },
});

// Update existing sidebar elements
client.updateModel({
  apiId: 'Product',
  sidebarElementsToUpsert: {
    sidebarElementsToUpdate: [
      {
        displayName: 'Product Analytics', // Current display name (identifier)
        newDisplayName: 'Analytics Dashboard',
        description: 'Updated analytics dashboard',
        position: 2,
      },
    ],
  },
});

// Delete custom sidebar elements
client.updateModel({
  apiId: 'Product',
  sidebarElementsToUpsert: {
    customSidebarElementsToDelete: [
      {
        appApiId: 'old-app',
        appElementApiId: 'old-element',
      },
    ],
  },
});

// Delete system sidebar elements
client.updateModel({
  apiId: 'Post',
  sidebarElementsToUpsert: {
    systemSidebarElementsToDelete: [
      {
        type: SystemSidebarElementType.VERSIONS,
      },
    ],
  },
});

// Comprehensive sidebar management
client.updateModel({
  apiId: 'Product',
  sidebarElementsToUpsert: {
    customSidebarElementsToCreate: [
      {
        displayName: 'New Analytics',
        appElementApiId: 'analytics-dashboard',
        appApiId: 'analytics-app',
        position: 0,
      },
    ],
    systemSidebarElementsToCreate: [
      {
        type: SystemSidebarElementType.INFORMATION,
        position: 1,
      },
    ],
    sidebarElementsToUpdate: [
      {
        displayName: 'Existing Element',
        newDisplayName: 'Updated Element',
        position: 2,
      },
    ],
    customSidebarElementsToDelete: [
      {
        appApiId: 'old-app',
        appElementApiId: 'old-element',
      },
    ],
    systemSidebarElementsToDelete: [
      {
        type: SystemSidebarElementType.VERSIONS,
      },
    ],
  },
});
```


**Enums**

- `SystemSidebarElementType`: `INFORMATION`, `STAGES`, `LOCALIZATIONS`, `VERSIONS`, `PREVIEW_URLS`, `RELEASES`, `CONTENT_WORKFLOWS`, `VARIANTS`

## Conditional visibility

You can modify the visibility conditions for a number of field types, such as simple, enumerable, component, relational, union, and taxonomy fields. The `visibilityCondition` parameter is available in the following methods:

    <div className="flex flex-col md:flex-row md:gap-4">
      <div className="flex-1">
        - `createSimpleField()`
        - `createEnumerableField()`
        - `createComponentField()`
        - `createRelationalField()`
        - `createUnionField()`
        - `createTaxonomyField()`
      </div>
      <div className="flex-1">
        - `updateSimpleField()`
        - `updateEnumerableField()`
        - `updateComponentField()`
        - `updateTaxonomyField()`
      </div>
    </div>

```ts
visibilityCondition?: {           // Optional: Show/hide field based on another field's value
  baseField: string,              // Required: API ID of the field that controls visibility
  operator: FieldConditionOperator, // Required: Comparison operator (IS, IS_NOT, etc.)
  enumerationValues?: string[],   // Required when baseField is enumeration type
  booleanValue?: boolean          // Required when baseField is boolean type
},
```

**Enums**
- `FieldConditionOperator`: `IS`, `IS_NOT`, `CONTAINS_ANY`, `CONTAINS_ALL`, `CONTAINS_NONE`

### Change visibility condition

**Use cases:**
- Showing/hiding fields based on other field values.
- Creating dynamic forms.
- Building conditional content structures.

**Important notes:**
- `baseField` is the API ID of the controlling field.
- For enumeration fields: use `enumerationValues` array.
- For boolean fields: use `booleanValue`.
- Operators: `IS`, `IS_NOT`, `CONTAINS_ANY`, `CONTAINS_ALL`, `CONTAINS_NONE`.
- Can be applied to: simple fields, component fields, relational fields, union fields, taxonomy fields.

```ts
// For an enumerable baseField
client.updateSimpleField({
  apiId: "conditionalFieldOne",
  parentApiId: "ModelApiId",
  visibilityCondition: {
    baseField: "buildingMaterial", // apiId of the baseField (in this case an enumerable field)
    operator: FieldConditionOperator.IS,
    enumerationValues: ["plexiGlass"], // an array of apiId for the referenced enumerationValues
  },
});

// OR with a boolean baseField
client.updateSimpleField({
  apiId: "conditionalFieldTwo",
  parentApiId: "ModelApiId",
  visibilityCondition: {
    baseField: "isMobileApp", // apiId of the baseField (in this case a boolean field)
    operator: FieldConditionOperator.IS,
    booleanValue: true,
  },
});

// Change from one condition to another
client.updateSimpleField({
  apiId: "conditionalField",
  parentApiId: "ModelApiId",
  visibilityCondition: {
    baseField: "status", // Changed from "buildingMaterial" to "status"
    operator: FieldConditionOperator.IS,
    enumerationValues: ["PUBLISHED"], // Changed enumeration values
  },
});
```

### Remove visibility condition

**Use cases:**
- Removing conditional visibility.
- Making fields always visible.
- Simplifying form structure.

**Important notes:**
- Set `visibilityCondition: null` to remove.
- Can also omit `visibilityCondition` parameter entirely.
- Field becomes always visible (based on visibility setting).

```ts
client.updateSimpleField({
  apiId: "conditionalFieldOne",
  parentApiId: "ModelApiId",
  visibilityCondition: null,
});
```

## Apps

### createAppInstallation()

Installs an app in the environment.

**Use cases:**
- Installing apps in environment.
- Adding app functionality.
- Enabling app features.

**Important notes:**
- Requires `appApiId`.
- `config` allows passing installation configuration.
- App must exist before installation.

  **Parameters**

```ts
client.createAppInstallation({
  appApiId: string,                 // Required: API ID of the app to install
  config: JSON                       // Required: App configuration (JSON object)
})
```


  **Examples**

```ts
// Basic app installation
client.createAppInstallation({
  appApiId: 'analytics-app',
  config: {
    apiKey: 'your-api-key',
    enabled: true,
  },
});

// App installation with complex config
client.createAppInstallation({
  appApiId: 'seo-app',
  config: {
    apiKey: 'seo-api-key',
    settings: {
      autoGenerateMetaTags: true,
      enableSitemap: true,
      sitemapUrl: 'https://example.com/sitemap.xml',
    },
    integrations: {
      googleSearchConsole: {
        enabled: true,
        propertyId: 'property-id',
      },
    },
  },
});
```


When an app is installed via the `createAppInstallation` method, it is always installed with the `PENDING` status. Users with the necessary permissions (usually the `ADMIN` or `DEVELOPER` roles) must complete the app installation process in Hygraph Studio.

Currently, to use the `createAppInstallation` method, the app needs to exist in at least one environment within the project. Users can't use this method to install new apps, only apps that they've previously installed in an existing environment.

### updateAppInstallation()

Updates an existing app installation.

**Use cases:**
- Updating app configuration.
- Enabling or disabling app installation.
- Modifying app settings.
- Updating app integration parameters
-Refreshing app configuration

**Important notes:**
- Only valid for App Token bearer. Must be called with an App Token (not a Permanent Auth Token).
- No `appApiId` parameter. The app installation is identified by the App Token making the request.
- `config` is merged with existing config (not replaced).
- `status` controls app installation status.

  **Parameters**

```ts
client.updateAppInstallation({
  config?: JSON,                    // Optional: App Installation config (merged with existing config)
  status?: AppInstallationStatus    // Optional: App Installation status
})
```

  
  **Examples**

```ts
// Update app configuration
client.updateAppInstallation({
  config: {
    apiKey: 'new-api-key',
    refreshInterval: 60,
    enabled: true,
  },
});

// Change app status

// Disable app installation
client.updateAppInstallation({
  status: AppInstallationStatus.DISABLED,
});

// Enable app installation
client.updateAppInstallation({
  status: AppInstallationStatus.COMPLETED,
});

// Partial config update

// Existing config: { apiKey: 'old', refreshInterval: 30, theme: 'light' }
// Update only refreshInterval
client.updateAppInstallation({
  config: {
    refreshInterval: 60, // Only this field is updated, others remain
  },
});
// Result: { apiKey: 'old', refreshInterval: 60, theme: 'light' }
```


**Enums**

- `AppInstallationStatus`: `PENDING`, `COMPLETED`, `DISABLED`.

### deleteAppInstallation()

Uninstalls an app from the environment.

**Use cases:**
- Uninstalling apps.
- Removing app functionality.

**Important notes:**
- Permanent deletion. This action cannot be undone.
- May affect sidebar elements and app fields.

  **Parameters**

```ts
client.deleteAppInstallation({
  appApiId: string,                 // Required: The API ID of the app to uninstall
})
```

  
  **Example**

```ts
// Uninstall an app
client.deleteAppInstallation({
  appApiId: 'analytics-app',
});

console.log('App uninstalled');
```


### Custom renderers and app fields

1. To create a simple field with custom table and form renderers in an environment, first retrieve the `appApiId` and `appElementApiId` using the Management API.

    ```graphql
    query test {
      viewer {
        project(id: "<projectId>") {
          environment(name: "<environment_name>") {
            appInstallation(appApiId: "<app_name>") {
              id
              app {
                id
                apiId
                elements {
                  id
                  apiId
                  type
                }
              }
            }
          }
        }
      }
    }
    ```

2. Now, create the simple field with custom table and form renderers in the specified environment.

    ```ts
    client.createSimpleField({
      environmentId: "<environment-id>",
      parentApiId: "Car",
      apiId: "appField",
      type: "STRING",
      displayName: "App Field",
      description: null,
      initialValue: null,
      tableRenderer: "CUSTOM",
      formRenderer: "CUSTOM",
      tableExtension: null,
      formExtension: null,
      formConfig: {
        alg_text_name: "Some custom text",
        appApiId: "myapp-test",
        appElementApiId: "myAppField"
      },
      tableConfig: {
        appApiId: "myapp-test",
        appElementApiId: "myAppField"
      },
      isList: false,
      isLocalized: false,
      isRequired: false,
      isUnique: false,
      isHidden: false,
      embeddableModels: [],
      visibility: "READ_WRITE",
      isTitle: false,
      position: 8,
      validations: null,
      embedsEnabled: null,
      visibilityCondition: null
    });
    ```