# Branches

## Create

`client.vals.branches.create(stringvalId, BranchCreateParamsbody, RequestOptionsoptions?): BranchCreateResponse`

**post** `/v2/vals/{val_id}/branches`

Create a new branch

### Parameters

- **valId:** `string`

- **body:** `BranchCreateParams`

  - **name:** `string`

  - **branchId:** `string`

    The branch ID to fork from. If this is not specified, the new branch will be forked from main.

### Returns

- `BranchCreateResponse`
  A Branch

  - **id:** `string`

    The id of the branch

  - **createdAt:** `string`

  - **forkedBranchId:** `string | null`

    The id of the branch this branch was forked from

  - **links:** `Links`

    - **html:** `string`

      The URL of this resource on Val Town

    - **self:** `string`

      The URL of this resource on this API

  - **name:** `string`

  - **updatedAt:** `string`

  - **version:** `number`

### Example

```node
import ValTown from '@valtown/sdk';

const client = new ValTown();

const branch = await client.vals.branches.create('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', {
  name: 'my-branch',
  branchId: '00000000-0000-0000-0000-000000000000',
});

console.log(branch.id);
```

## Retrieve

`client.vals.branches.retrieve(stringvalId, stringbranchId, RequestOptionsoptions?): BranchRetrieveResponse`

**get** `/v2/vals/{val_id}/branches/{branch_id}`

Get a branch by id

### Parameters

- **valId:** `string`

- **branchId:** `string`

### Returns

- `BranchRetrieveResponse`
  A Branch

  - **id:** `string`

    The id of the branch

  - **createdAt:** `string`

  - **forkedBranchId:** `string | null`

    The id of the branch this branch was forked from

  - **links:** `Links`

    - **html:** `string`

      The URL of this resource on Val Town

    - **self:** `string`

      The URL of this resource on this API

  - **name:** `string`

  - **updatedAt:** `string`

  - **version:** `number`

### Example

```node
import ValTown from '@valtown/sdk';

const client = new ValTown();

const branch = await client.vals.branches.retrieve(
  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
);

console.log(branch.id);
```

## List

`client.vals.branches.list(stringvalId, BranchListParamsquery, RequestOptionsoptions?): PageCursorURL<BranchListResponse>`

**get** `/v2/vals/{val_id}/branches`

List all branches for a val

### Parameters

- **valId:** `string`

- **query:** `BranchListParams`

  - **limit:** `number`

    Maximum items to return in each paginated response

  - **offset:** `number`

    Number of items to skip in order to deliver paginated results

### Returns

- `BranchListResponse`
  A Branch

  - **id:** `string`

    The id of the branch

  - **createdAt:** `string`

  - **forkedBranchId:** `string | null`

    The id of the branch this branch was forked from

  - **links:** `Links`

    - **html:** `string`

      The URL of this resource on Val Town

    - **self:** `string`

      The URL of this resource on this API

  - **name:** `string`

  - **updatedAt:** `string`

  - **version:** `number`

### Example

```node
import ValTown from '@valtown/sdk';

const client = new ValTown();

// Automatically fetches more pages as needed.
for await (const branchListResponse of client.vals.branches.list('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', {
  limit: 1,
  offset: 0,
})) {
  console.log(branchListResponse.id);
}
```

## Delete

`client.vals.branches.delete(stringvalId, stringbranchId, RequestOptionsoptions?): void`

**delete** `/v2/vals/{val_id}/branches/{branch_id}`

Delete a branch

### Parameters

- **valId:** `string`

- **branchId:** `string`

### Example

```node
import ValTown from '@valtown/sdk';

const client = new ValTown();

await client.vals.branches.delete(
  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
);
```