> For the complete documentation index, see [llms.txt](https://docs.specifyapp.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.specifyapp.com/reference/sdtf-engine/mutation-api.md).

# Mutation API

You access each of the mutation methods over:

```typescript
sdtfEngine.mutation.[method]
```

### `addToken`

Add a new token to the token tree.

```typescript
function addToken(param:{
  parentPath: Array<string>,
  name: string,
  tokenProperties: {
    $type: string;
    $value: unknown;
    $description?: string;
    $extensions?: Record<string, unknown>;
  },
}): void;
```

### `renameToken`

Rename a token.

```typescript
function renameToken(param: { atPath: Array<string>; name: string }): void;
```

### `updateTokenDescription`

Update the description of a token.

```typescript
function updateTokenDescription(param: {
  atPath: Array<string>;
  description: string;
}): void;
```

### `updateTokenExtensions`

Update the extensions of a token.

```typescript
function updateTokenExtensions(param: {
  atPath: Array<string>;
  extensions: treeNodeExtensionsSchema;
}): void;
```

### `updateTokenValue`

Update the value of a token.

```typescript
function updateTokenValue(param:{
  atPath: Array<string>,
  // We cannot know with type of the value since no type is enforced
  value: unknown,
}): void;
```

### `updateTokenModeValue`

Update the value of a token for a given mode.

```typescript
function updateTokenModeValue(param:{
    mode: string,
    // We cannot know with type of the value since no type is enforced
    value: unknown,
}): void;
```

### `renameTokenMode`

Rename a token mode.

```typescript
function renameTokenMode(param: {
  atPath: Array<string>;
  fromMode: string;
  toMode: string;
}): void;
```

### `createTokenModeValue`

Create a new token mode value.

```typescript
function createTokenModeValue(param:{
  atPath: Array<string>,
  mode: string,
  // We cannot know with type of the value since no type is enforced
  value: unknown,
}): void;
```

### `deleteTokenModeValue`

Delete a token mode value.

```typescript
function deleteTokenModeValue(param: {
  atPath: Array<string>;
  mode: string;
}): void;
```

### `deleteToken`

Delete a token.

```typescript
function deleteToken(param: { atPath: Array<string> }): void;
```

### `moveToken`

Move a token.

```typescript
function moveToken(param: {
  atPath: Array<string>;
  toPath: Array<string>;
}): void;
```

### `addCollection`

Add a new collection to the token tree.

```typescript
function addCollection(param: {
  parentPath: Array<string>;
  name: string;
  collectionProperties: { 
    $collection: {$modes: Array<string>};
    $description?: string;
    $extensions?: Record<string, unknown>;
  };
}): void;
```

### `renameCollection`

Rename a collection.

```typescript
function renameCollection(param: {
  atPath: Array<string>;
  name: string;
}): void;
```

### `updateCollectionDescription`

Update the description of a collection.

```typescript
function updateCollectionDescription(param: {
  atPath: Array<string>;
  description: string;
}): void;
```

### `updateCollectionExtensions`

Update the extensions of a collection.

```typescript
function updateCollectionExtensions(param: {
  atPath: Array<string>;
  extensions: treeNodeExtensionsSchema;
}): void;
```

### `renameCollectionMode`

Rename a collection mode.

```typescript
function renameCollectionMode(param: {
  atPath: Array<string>;
  fromMode: string;
  toMode: string;
}): void;
```

### `truncateCollection`

Truncate a collection.

```typescript
function truncateCollection(param: { atPath: Array<string> }): void;
```

### `deleteCollection`

Delete a collection.

```typescript
function deleteCollection(param: { atPath: Array<string> }): void;
```

### `deleteCollectionMode`

Delete a collection mode.

```typescript
function deleteCollectionMode(param: {
  atPath: Array<string>;
  mode: string;
}): void;
```

### `moveCollection`

Move a collection.

```typescript
function moveCollection(param: {
  atPath: Array<string>;
  toPath: Array<string>;
}): void;
```

### `addGroup`

Add a new group to the token tree.

```typescript
function addGroup(param: {
  parentPath: Array<string>;
  name: string;
  groupProperties: specifyGroupPropertiesSchema;
}): void;
```

### `renameGroup`

Rename a group.

```typescript
function renameGroup(param: { atPath: Array<string>; name: string }): void;
```

### `updateGroupDescription`

Update the description of a group.

```typescript
function updateGroupDescription(param: {
  atPath: Array<string>;
  description: string;
}): void;
```

### `updateGroupExtensions`

Update the extensions of a group.

```typescript
function updateGroupExtensions(param: {
  atPath: Array<string>;
  extensions: treeNodeExtensionsSchema;
}): void;
```

### `truncateGroup`

Truncate a group.

```typescript
function truncateGroup(param: { atPath: Array<string> }): void;
```

### `deleteGroup`

Delete a group.

```typescript
function deleteGroup(param: { atPath: Array<string> }): void;
```

### `moveGroup`

Move a group.

```typescript
function moveGroup(param: {
  atPath: Array<string>;
  toPath: Array<string>;
}): void;
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.specifyapp.com/reference/sdtf-engine/mutation-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.