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.

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 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.

#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.

• 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.

#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).

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.

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:

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).

#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.

#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.

#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.

#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.

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.

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.

#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).

#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

#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.

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.

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.

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)

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.

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).

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.

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.

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.

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.

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.

#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.

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.

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.

#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).

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.

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

#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.

#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.

#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.

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.

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.

#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.

#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.

#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.

#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.

#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.

#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.

#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.

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.

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.

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.

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.

#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.

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.

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.

#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.

#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.

#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.

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:

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.

// 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).

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.

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.

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.

#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.

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

   Copy

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

   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
   });

   Copy