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

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

The question should be specific, self-contained, and written in natural language.
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.