Changesets

A changeset is a draft that stages edits to content resources and applies them together on commit.

A changeset holds a set of staged changes, one per content resource it touches, each a create, update, or delete. It records who opened it, its current status, and the timestamps of each transition it passes through. Committing a changeset applies every staged change at once, so mutually dependent edits across many resources land in a single step. Each committed change increments the affected resource's version. A changeset is itself an organization-scoped resource, addressed by an id prefixed CHG_, and reachable through the API, the MCP server, or the web app.

Status

A changeset has a status, one of four values that reflects its stage.

• draft is a private working changeset. You can stage changes into it and commit it. Only the user who created it can see it, unless the platform or the Simba agent created it rather than a user.
• proposed is a changeset submitted for review. You can still stage changes into it and commit it. Every member of the organization can see it. The user who created it can move it back to draft, and only they can.
• committed is a changeset whose staged changes have been applied. It is terminal and read-only.
• declined is a proposed changeset the reviewer rejected without committing. It is terminal and read-only, and every member of the organization can see it.

Changes

Each entry in changes is a staged edit to one content resource. It carries the resource's full payload plus the overlay fields below that describe how the edit relates to the committed state. Every field is system-generated. Staging a change is a side effect of creating, updating, or deleting the underlying resource within the changeset.

Field	Type	Description
operation	enum	The kind of edit. One of create, update, or delete.
resourceKind	enum	The kind of resource this change targets. One of Dashboard, Folder, Integration, Lookup, Mapper, Parser, Detection, Connector, ContentPack, ContentPackInstallation, Table, Union, View, WebhookConfig, HttpToolConfig, McpConfig, or Skill.
fieldConflicts	array<object>	Per-field conflicts detected against the latest committed version of the resource. Null when there is no conflict. See Field conflicts.
latestCommittedVersion	integer	Version number of the resource as last committed outside this changeset. Null when the resource has no committed version.
contentPackId	string	The content pack this change targets, when the edit is to pack content. Prefixed PAK_.
parentIntegrationId	string	On a Mapper or Parser change, the integration the resource belongs to. Prefixed INT_.

Field conflicts

Each entry in a change's fieldConflicts records one field where the staged edit diverges from the resource's latest committed state.

Field	Type	Description
fieldName	string	Name of the conflicting field.
baseValue	unknown	The field's value at the version the change was based on. Null when absent.
latestValue	unknown	The field's value in the latest committed version. Null when absent.
proposedValue	unknown	The field's value the staged change would set. Null when absent.
isMultiline	boolean	Whether the field holds multiline text. The web app uses it to render the conflict.

Validation result

Validating a changeset returns a validation result, the shape a full-batch commit check produces against a draft or proposed changeset.

Field	Type	Description
valid	boolean	Whether every staged change passes commit validation.
errors	array<object>	The validation errors found. Empty when valid is true.

Each entry in errors names one problem.

Field	Type	Description
resourceKind	string	The kind of resource the error is on.
resourceName	string	The name of the resource the error is on.
message	string	What is wrong.
resourceId	string	The resource the error is on. Absent for a resource with no ID yet.
field	string	The specific field the error is on, when the error is field-scoped.

Inputs

Field	Type	Required	Description
name	string	Optional	Display name of the changeset. An unnamed changeset shows as "Untitled changeset" in the web app.
description	string	Optional	Free-text description of the changeset.

Outputs

Field	Type	Description
status	enum	Life-cycle state of the changeset. One of draft, proposed, committed, or declined. See Status for what each means.
changes	array<object>	The staged changes the changeset holds, one per resource it touches. See Changes. Present when a changeset is fetched by ID.
createdByChatId	string	The Simba agent chat that created the changeset, prefixed CHT_. Null when a user created it directly.
proposedAt	timestamp	When the changeset moved to proposed. Null when it was never proposed.
proposedByUserId	string	The user who proposed the changeset, prefixed USR_. Null when it was never proposed.
committedAt	timestamp	When the changeset was committed. Null until committed.
committedByUserId	string	The user who committed the changeset, prefixed USR_. Null until committed.
declinedAt	timestamp	When the changeset was declined. Null unless declined.
declinedByUserId	string	The user who declined the changeset, prefixed USR_. Null unless declined.

Plus the common resource fields. createdByUserId is null when the platform or the Simba agent created the changeset rather than a user.

Related

• Content, the resources a changeset stages edits to.
• Spaces, the boundary the content a changeset edits lives within.