# BoxApi

All URIs are relative to *https://ascii.dev/api/box/v1*

| Method | HTTP request | Description |
|------------- | ------------- | -------------|
| [**addEnvironmentRepo**](BoxApi.md#addenvironmentrepooperation) | **POST** /environments/{environmentId}/repos | Add a repository to an environment |
| [**apiKeyUsage**](BoxApi.md#apikeyusage) | **GET** /api-keys/{apiKeyId}/usage | Get API key usage |
| [**apiKeys**](BoxApi.md#apikeys) | **GET** /api-keys | List API keys |
| [**artifact**](BoxApi.md#artifact) | **GET** /boxes/{boxId}/artifacts | Download a Boat artifact |
| [**boxes**](BoxApi.md#boxes) | **GET** /boxes | List boxes |
| [**command**](BoxApi.md#commandoperation) | **POST** /boxes/{boxId}/commands | Execute a command in a Boat |
| [**commandStatus**](BoxApi.md#commandstatus) | **GET** /boxes/{boxId}/commands/{processId} | Get detached command status and logs |
| [**conversations**](BoxApi.md#conversations) | **GET** /boxes/{boxId}/conversations | List box conversations |
| [**create**](BoxApi.md#create) | **POST** /boxes | Create box |
| [**createEnvironment**](BoxApi.md#createenvironment) | **POST** /environments | Create a Boat environment |
| [**createScopedApiKey**](BoxApi.md#createscopedapikeyoperation) | **POST** /api-keys/scoped | Create a scoped API key |
| [**createWebhook**](BoxApi.md#createwebhook) | **POST** /webhooks | Create webhook |
| [**deleteBox**](BoxApi.md#deletebox) | **DELETE** /boxes/{boxId} | Permanently delete Boat data |
| [**deleteEnvironment**](BoxApi.md#deleteenvironment) | **DELETE** /environments/{environmentId} | Delete a Boat environment |
| [**deleteEnvironmentRepo**](BoxApi.md#deleteenvironmentrepo) | **DELETE** /environments/{environmentId}/repos/{repositoryId} | Remove a repository from an environment |
| [**deleteEnvironmentSecretFile**](BoxApi.md#deleteenvironmentsecretfile) | **DELETE** /environments/{environmentId}/secret-files | Remove one secret file |
| [**deleteEnvironmentVar**](BoxApi.md#deleteenvironmentvar) | **DELETE** /environments/{environmentId}/vars/{key} | Remove one environment variable |
| [**deleteNamedSnapshot**](BoxApi.md#deletenamedsnapshot) | **DELETE** /named-snapshots/{name} | Remove a named snapshot |
| [**deleteSnapshot**](BoxApi.md#deletesnapshot) | **DELETE** /snapshots/{snapshotId} | Permanently delete snapshot data |
| [**deleteWebhook**](BoxApi.md#deletewebhook) | **DELETE** /webhooks/{webhookId} | Delete webhook |
| [**desktop**](BoxApi.md#desktopoperation) | **POST** /boxes/{boxId}/desktop | Get desktop streaming URL |
| [**environments**](BoxApi.md#environments) | **GET** /environments | List Boat environments |
| [**events**](BoxApi.md#events) | **GET** /boxes/{boxId}/events | List box events |
| [**fork**](BoxApi.md#forkoperation) | **POST** /boxes/{boxId}/fork | Fork box |
| [**get**](BoxApi.md#get) | **GET** /boxes/{boxId} | Get box |
| [**getDataRetention**](BoxApi.md#getdataretention) | **GET** /account/data-retention | Get account data-retention policy |
| [**getDeletionOperation**](BoxApi.md#getdeletionoperation) | **GET** /deletion-operations/{operationId} | Get deletion operation |
| [**getLatestBoxSnapshot**](BoxApi.md#getlatestboxsnapshot) | **GET** /boxes/{boxId}/snapshots/latest | Get latest box snapshot |
| [**getNamedSnapshot**](BoxApi.md#getnamedsnapshot) | **GET** /named-snapshots/{name} | Get a named snapshot |
| [**getSnapshotDownload**](BoxApi.md#getsnapshotdownload) | **GET** /snapshots/{snapshotId}/download | Get snapshot download |
| [**getSnapshotFile**](BoxApi.md#getsnapshotfile) | **GET** /snapshots/{snapshotId}/files | Download a file or folder from a snapshot |
| [**getSnapshotTree**](BoxApi.md#getsnapshottree) | **GET** /snapshots/{snapshotId}/tree | Get snapshot file tree |
| [**getWebhook**](BoxApi.md#getwebhook) | **GET** /webhooks/{webhookId} | Get webhook |
| [**hostPort**](BoxApi.md#hostportoperation) | **POST** /boxes/{boxId}/host | Expose a box port on a public HTTPS URL |
| [**interrupt**](BoxApi.md#interrupt) | **POST** /boxes/{boxId}/interrupt | Interrupt running work |
| [**limits**](BoxApi.md#limits) | **GET** /limits | Get Boat limits |
| [**listBoxSnapshots**](BoxApi.md#listboxsnapshots) | **GET** /boxes/{boxId}/snapshots | List box snapshots |
| [**listNamedSnapshots**](BoxApi.md#listnamedsnapshots) | **GET** /named-snapshots | List named snapshots |
| [**listSnapshots**](BoxApi.md#listsnapshots) | **GET** /snapshots | List snapshots |
| [**listWebhooks**](BoxApi.md#listwebhooks) | **GET** /webhooks | List webhooks |
| [**me**](BoxApi.md#me) | **GET** /me | Get current Boat user |
| [**prompt**](BoxApi.md#promptoperation) | **POST** /boxes/{boxId}/prompt | Prompt Boat |
| [**promptRunStatus**](BoxApi.md#promptrunstatus) | **GET** /boxes/{boxId}/prompts/{promptId} | Get prompt run status |
| [**readFile**](BoxApi.md#readfile) | **GET** /boxes/{boxId}/files | Read a file from a Boat |
| [**repos**](BoxApi.md#repos) | **GET** /repos | List GitHub repositories available to Boat |
| [**resume**](BoxApi.md#resumeoperation) | **POST** /boxes/{boxId}/resume | Resume box |
| [**revokeApiKey**](BoxApi.md#revokeapikey) | **DELETE** /api-keys/{apiKeyId} | Revoke an API key |
| [**rotateApiKey**](BoxApi.md#rotateapikey) | **POST** /api-keys/{apiKeyId}/rotate | Rotate an API key |
| [**rotateWebhookSigningSecret**](BoxApi.md#rotatewebhooksigningsecret) | **POST** /webhooks/{webhookId}/rotate | Rotate webhook signing secret |
| [**saveNamedSnapshot**](BoxApi.md#savenamedsnapshot) | **POST** /named-snapshots | Save a named snapshot |
| [**secrets**](BoxApi.md#secrets) | **GET** /secrets | Get Boat secrets setup |
| [**selectRepo**](BoxApi.md#selectrepo) | **POST** /repos | Select repository for boxes |
| [**setEnvironmentSecretFile**](BoxApi.md#setenvironmentsecretfileoperation) | **PUT** /environments/{environmentId}/secret-files | Write one secret file |
| [**setEnvironmentVar**](BoxApi.md#setenvironmentvaroperation) | **PUT** /environments/{environmentId}/vars/{key} | Set one environment variable |
| [**sshKey**](BoxApi.md#sshkeyoperation) | **POST** /boxes/{boxId}/sshkey | Configure box SSH key |
| [**steer**](BoxApi.md#steeroperation) | **POST** /boxes/{boxId}/steer | Steer a running turn |
| [**stop**](BoxApi.md#stopoperation) | **POST** /boxes/{boxId}/stop | Stop and archive box |
| [**update**](BoxApi.md#update) | **PATCH** /boxes/{boxId} | Update box |
| [**updateDataRetention**](BoxApi.md#updatedataretention) | **PATCH** /account/data-retention | Update account data-retention policy |
| [**updateEnvironment**](BoxApi.md#updateenvironment) | **PUT** /environments/{environmentId} | Update a Boat environment |
| [**updateSecrets**](BoxApi.md#updatesecrets) | **POST** /secrets | Update Boat secrets setup |
| [**updateWebhook**](BoxApi.md#updatewebhook) | **PATCH** /webhooks/{webhookId} | Update webhook |
| [**upgradeEnvironment**](BoxApi.md#upgradeenvironment) | **POST** /environments/{environmentId}/upgrade | Upgrade boxes to an environment\'s latest version |
| [**usage**](BoxApi.md#usage) | **GET** /boxes/{boxId}/usage | Get box usage |
| [**writeFile**](BoxApi.md#writefile) | **PUT** /boxes/{boxId}/files | Write a file in a Boat |



## addEnvironmentRepo

> EnvironmentItemChangeResponse addEnvironmentRepo(environmentId, addEnvironmentRepoRequest)

Add a repository to an environment

Adds a repository (or updates its base branch) by database id from the repository list. Mints a new immutable version.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { AddEnvironmentRepoOperationRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string
    environmentId: 38400000-8cf0-11bd-b23e-10b96e4ef00d,
    // AddEnvironmentRepoRequest
    addEnvironmentRepoRequest: ...,
  } satisfies AddEnvironmentRepoOperationRequest;

  try {
    const data = await api.addEnvironmentRepo(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **environmentId** | `string` |  | [Defaults to `undefined`] |
| **addEnvironmentRepoRequest** | [AddEnvironmentRepoRequest](AddEnvironmentRepoRequest.md) |  | |

### Return type

[**EnvironmentItemChangeResponse**](EnvironmentItemChangeResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: `application/json`
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | New version minted. |  -  |
| **400** | Invalid request body or parameters. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **404** | Resource not found. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## apiKeyUsage

> ApiKeyUsageResponse apiKeyUsage(apiKeyId)

Get API key usage

Returns the key\'s request total for the 30-day UTC window and the boxes and Agents it created that still exist, including Boxes that never got a Sandbox row. Works for revoked keys owned by the authenticated account.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { ApiKeyUsageRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string | API key ID returned by `GET /api-keys`.
    apiKeyId: apiKeyId_example,
  } satisfies ApiKeyUsageRequest;

  try {
    const data = await api.apiKeyUsage(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **apiKeyId** | `string` | API key ID returned by `GET /api-keys`. | [Defaults to `undefined`] |

### Return type

[**ApiKeyUsageResponse**](ApiKeyUsageResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: Not defined
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | Usage and created resources for the key. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **404** | Resource not found. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## apiKeys

> ApiKeysResponse apiKeys()

List API keys

Lists API key metadata only. Raw key secrets are not returned after creation/rotation. Results include expiry and scope. A restricted API-key caller receives `apiKeys: []`; only an unrestricted account key or browser/CLI session receives the account inventory. Bearer header is unchanged; scope lives on the key.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { ApiKeysRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  try {
    const data = await api.apiKeys();
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters

This endpoint does not need any parameter.

### Return type

[**ApiKeysResponse**](ApiKeysResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: Not defined
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | API key metadata. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **403** | Authenticated token is not allowed to perform this action. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## artifact

> Blob artifact(boxId, path)

Download a Boat artifact

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { ArtifactRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string | Public Box id returned by create/list/get box calls.
    boxId: boxId_example,
    // string
    path: path_example,
  } satisfies ArtifactRequest;

  try {
    const data = await api.artifact(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **boxId** | `string` | Public Box id returned by create/list/get box calls. | [Defaults to `undefined`] |
| **path** | `string` |  | [Defaults to `undefined`] |

### Return type

**Blob**

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: Not defined
- **Accept**: `application/octet-stream`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | Artifact bytes. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## boxes

> BoxListResponse boxes(limit, cursor, sort, state)

List boxes

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { BoxesRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // number | Maximum items to return. (optional)
    limit: 56,
    // string | Opaque pagination cursor returned as `pageInfo.nextCursor`. (optional)
    cursor: cursor_example,
    // 'asc' | 'desc' | Sort direction for cursor pagination. (optional)
    sort: sort_example,
    // string | Comma-separated Box state filter, for example `ready,idle,running`. (optional)
    state: state_example,
  } satisfies BoxesRequest;

  try {
    const data = await api.boxes(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **limit** | `number` | Maximum items to return. | [Optional] [Defaults to `100`] |
| **cursor** | `string` | Opaque pagination cursor returned as `pageInfo.nextCursor`. | [Optional] [Defaults to `undefined`] |
| **sort** | `asc`, `desc` | Sort direction for cursor pagination. | [Optional] [Defaults to `'desc'`] [Enum: asc, desc] |
| **state** | `string` | Comma-separated Box state filter, for example `ready,idle,running`. | [Optional] [Defaults to `undefined`] |

### Return type

[**BoxListResponse**](BoxListResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: Not defined
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | Boxes owned by the authenticated Boat user. |  -  |
| **401** | Missing or invalid bearer token. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## command

> Command200Response command(boxId, commandRequest)

Execute a command in a Boat

Runs the command synchronously by default (timeout configurable via `timeoutSeconds`, 600s cap). With `detached: true` the command starts in the background and a process id is returned immediately; poll `/boxes/{boxId}/commands/{processId}` for status and logs. Returns 400 invalid_timeout when `timeoutSeconds` is not an integer in 1-600. Returns 409 box_starting (retryable) while the Boat is still provisioning -- wait until the Boat state is ready before running commands. Command execution is never retried automatically: a 502 box_direct_failed means the command may already be running on the Boat.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { CommandOperationRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string | Public Box id returned by create/list/get box calls.
    boxId: boxId_example,
    // CommandRequest
    commandRequest: ...,
  } satisfies CommandOperationRequest;

  try {
    const data = await api.command(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **boxId** | `string` | Public Box id returned by create/list/get box calls. | [Defaults to `undefined`] |
| **commandRequest** | [CommandRequest](CommandRequest.md) |  | |

### Return type

[**Command200Response**](Command200Response.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: `application/json`
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | Command result (synchronous) or process start confirmation (detached). |  -  |
| **400** | Invalid request body or parameters. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **404** | Resource not found. |  -  |
| **409** | Request conflicts with current account or box state. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## commandStatus

> CommandStatusResponse commandStatus(boxId, processId, tailBytes)

Get detached command status and logs

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { CommandStatusRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string | Public Box id returned by create/list/get box calls.
    boxId: boxId_example,
    // number | Process id returned by a detached command start.
    processId: 56,
    // number | Cap each returned log to its last N bytes. Defaults to 524288 (512 KiB). (optional)
    tailBytes: 56,
  } satisfies CommandStatusRequest;

  try {
    const data = await api.commandStatus(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **boxId** | `string` | Public Box id returned by create/list/get box calls. | [Defaults to `undefined`] |
| **processId** | `number` | Process id returned by a detached command start. | [Defaults to `undefined`] |
| **tailBytes** | `number` | Cap each returned log to its last N bytes. Defaults to 524288 (512 KiB). | [Optional] [Defaults to `undefined`] |

### Return type

[**CommandStatusResponse**](CommandStatusResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: Not defined
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | Process status and log tails. |  -  |
| **400** | Invalid request body or parameters. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **404** | Resource not found. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## conversations

> ConversationsResponse conversations(boxId)

List box conversations

Every conversation on the Box, most recently prompted first, with what you need to pick one: how many prompts it holds, whether a turn is running in it right now, the last harness and model it ran on, a preview of its last prompt, and `current`, the one a `POST /prompt` without `new` or `conversationId` would continue. Pass an `id` back as `conversationId` on `POST /prompt` to resume that thread, or as `conversation` on `POST /steer`, `POST /interrupt` and `GET /events` to scope those. See [Integrated agents](/box/integrated-agents).

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { ConversationsRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string | Public Box id returned by create/list/get box calls.
    boxId: boxId_example,
  } satisfies ConversationsRequest;

  try {
    const data = await api.conversations(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **boxId** | `string` | Public Box id returned by create/list/get box calls. | [Defaults to `undefined`] |

### Return type

[**ConversationsResponse**](ConversationsResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: Not defined
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | Conversations on the Box. A Box that was never prompted returns an empty list. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **402** | Account cannot currently create or operate Boxes. The error body may include a dashboard billing URL, but billing actions are not part of the v1 API. |  -  |
| **404** | Resource not found. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## create

> CreateBoxResponse create(idempotencyKey, org, xBoxOrg, createBoxRequest)

Create box

Provision a new cloud computer. Store the returned `box.id` with your product job/session record. Send an `Idempotency-Key` header to make this call safe to retry after a lost response without creating a second billable box.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { CreateRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string | Optional exactly-once key for creating a box. Send your own opaque, account-unique value (a UUID) to make `POST /boxes` safe to retry when the response is lost (network timeout, 5xx): the first request creates the box and binds it to the key; every later request with the **same account, key, and request body** returns that same box instead of creating a second, billable one. Behavior: keys are retained for **24 hours**; a concurrent or early retry while the first box is still being minted returns `409` `idempotency_in_progress` (retry shortly, same key); reusing a key with a **different body** returns `409` `idempotency_key_reused`; timeouts and 5xx are safe to retry with the same key; a create that fails before the box exists releases the key within ~2 minutes so a retry can create the box. Omit the header to keep the default (non-idempotent) behavior. (optional)
    idempotencyKey: idempotencyKey_example,
    // string | Billing wallet for this request. A team id you belong to reads that team\'s limits / bills a create to that team. Your own account id is personal. Boxes, snapshots, and environments stay creator-private. (optional)
    org: org_example,
    // string | Same as the `org` query parameter. Query wins when both are set. (optional)
    xBoxOrg: xBoxOrg_example,
    // CreateBoxRequest (optional)
    createBoxRequest: ...,
  } satisfies CreateRequest;

  try {
    const data = await api.create(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **idempotencyKey** | `string` | Optional exactly-once key for creating a box. Send your own opaque, account-unique value (a UUID) to make `POST /boxes` safe to retry when the response is lost (network timeout, 5xx): the first request creates the box and binds it to the key; every later request with the **same account, key, and request body** returns that same box instead of creating a second, billable one. Behavior: keys are retained for **24 hours**; a concurrent or early retry while the first box is still being minted returns `409` `idempotency_in_progress` (retry shortly, same key); reusing a key with a **different body** returns `409` `idempotency_key_reused`; timeouts and 5xx are safe to retry with the same key; a create that fails before the box exists releases the key within ~2 minutes so a retry can create the box. Omit the header to keep the default (non-idempotent) behavior. | [Optional] [Defaults to `undefined`] |
| **org** | `string` | Billing wallet for this request. A team id you belong to reads that team\'s limits / bills a create to that team. Your own account id is personal. Boxes, snapshots, and environments stay creator-private. | [Optional] [Defaults to `undefined`] |
| **xBoxOrg** | `string` | Same as the `org` query parameter. Query wins when both are set. | [Optional] [Defaults to `undefined`] |
| **createBoxRequest** | [CreateBoxRequest](CreateBoxRequest.md) |  | [Optional] |

### Return type

[**CreateBoxResponse**](CreateBoxResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: `application/json`
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **202** | Box accepted for provisioning. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **402** | Account cannot currently create or operate Boxes. The error body may include a dashboard billing URL, but billing actions are not part of the v1 API. |  -  |
| **409** | Request conflicts with current account or box state. |  -  |
| **429** | Machine start or concurrent-box limit reached. Create, fork and resume each count as one machine start against your plan\'s start limits (see the Billing guide; `rate_limited`, naming the window you hit). A box that would exceed your plan\'s concurrent-box cap is refused with `limit_reached`, or `member_limit_reached` when an organization owner has capped you below the plan. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## createEnvironment

> BoxEnvironmentListResponse createEnvironment(createBoxEnvironmentRequest)

Create a Boat environment

Create a new named environment. It starts on version 1 with all fine-grained flags on and `safeForThirdParties` off.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { CreateEnvironmentRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // CreateBoxEnvironmentRequest
    createBoxEnvironmentRequest: ...,
  } satisfies CreateEnvironmentRequest;

  try {
    const data = await api.createEnvironment(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **createBoxEnvironmentRequest** | [CreateBoxEnvironmentRequest](CreateBoxEnvironmentRequest.md) |  | |

### Return type

[**BoxEnvironmentListResponse**](BoxEnvironmentListResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: `application/json`
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | Environment created; full list returned. |  -  |
| **400** | Invalid request body or parameters. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **409** | Request conflicts with current account or box state. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## createScopedApiKey

> ApiKeySecretResponse createScopedApiKey(createScopedApiKeyRequest)

Create a scoped API key

Creates a scoped, expiring API key. Requires a dashboard/CLI session or an admin-scoped token. The secret is returned once. This dedicated path returns a typed 503 until scoped credential creation is activated.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { CreateScopedApiKeyOperationRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // CreateScopedApiKeyRequest
    createScopedApiKeyRequest: ...,
  } satisfies CreateScopedApiKeyOperationRequest;

  try {
    const data = await api.createScopedApiKey(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **createScopedApiKeyRequest** | [CreateScopedApiKeyRequest](CreateScopedApiKeyRequest.md) |  | |

### Return type

[**ApiKeySecretResponse**](ApiKeySecretResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: `application/json`
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **201** | Created key metadata plus the one-time secret. |  -  |
| **400** | Invalid request body or parameters. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **403** | Authenticated token is not allowed to perform this action. |  -  |
| **503** | Scoped credential creation has not been activated yet. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## createWebhook

> WebhookSecretResponse createWebhook(webhookCreateRequest)

Create webhook

Registers an account-wide endpoint for Boat lifecycle events. The endpoint must use HTTPS on port 443 and resolve only to public addresses. Redirects are not followed during delivery.  The signing secret is returned only in this response. An account can register at most 10 unique endpoint URLs. 

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { CreateWebhookRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // WebhookCreateRequest
    webhookCreateRequest: {"name":"Production automation","url":"https://example.com/hooks/box","events":["box.ready","box.error"]},
  } satisfies CreateWebhookRequest;

  try {
    const data = await api.createWebhook(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **webhookCreateRequest** | [WebhookCreateRequest](WebhookCreateRequest.md) |  | |

### Return type

[**WebhookSecretResponse**](WebhookSecretResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: `application/json`
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **201** | Webhook created. Store the one-time signing secret now. |  -  |
| **400** | Invalid request body or parameters. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **409** | Request conflicts with current account or box state. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## deleteBox

> DeletionOperationResponse deleteBox(xAsciiConfirmDelete, boxId)

Permanently delete Boat data

Accept irreversible background deletion of the Boat machine, snapshots, and content-bearing records. This is not archive: the Boat cannot be resumed. Named snapshots and other shared artifacts remain independent. Poll the returned operation until `completed`.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { DeleteBoxRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string | Must exactly equal the target `boxId` or `snapshotId`. A missing or mismatched value returns `409` without accepting deletion.
    xAsciiConfirmDelete: xAsciiConfirmDelete_example,
    // string | Public Box id returned by create/list/get box calls.
    boxId: boxId_example,
  } satisfies DeleteBoxRequest;

  try {
    const data = await api.deleteBox(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **xAsciiConfirmDelete** | `string` | Must exactly equal the target `boxId` or `snapshotId`. A missing or mismatched value returns `409` without accepting deletion. | [Defaults to `undefined`] |
| **boxId** | `string` | Public Box id returned by create/list/get box calls. | [Defaults to `undefined`] |

### Return type

[**DeletionOperationResponse**](DeletionOperationResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: Not defined
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **202** | Deletion confirmed and accepted for background processing. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **403** | Authenticated token is not allowed to perform this action. |  -  |
| **404** | Resource not found. |  -  |
| **409** | Request conflicts with current account or box state. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## deleteEnvironment

> BoxEnvironmentResponse deleteEnvironment(environmentId)

Delete a Boat environment

Soft-deletes an environment. The default environment cannot be deleted, and at least one environment is always kept.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { DeleteEnvironmentRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string | Environment id returned by `GET /environments`.
    environmentId: 38400000-8cf0-11bd-b23e-10b96e4ef00d,
  } satisfies DeleteEnvironmentRequest;

  try {
    const data = await api.deleteEnvironment(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **environmentId** | `string` | Environment id returned by `GET /environments`. | [Defaults to `undefined`] |

### Return type

[**BoxEnvironmentResponse**](BoxEnvironmentResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: Not defined
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | Environment soft-deleted. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **404** | Resource not found. |  -  |
| **409** | Request conflicts with current account or box state. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## deleteEnvironmentRepo

> EnvironmentItemChangeResponse deleteEnvironmentRepo(environmentId, repositoryId)

Remove a repository from an environment

Removes one repository from the environment\'s selection. Mints a new immutable version.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { DeleteEnvironmentRepoRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string
    environmentId: 38400000-8cf0-11bd-b23e-10b96e4ef00d,
    // string | The repository `databaseId`.
    repositoryId: repositoryId_example,
  } satisfies DeleteEnvironmentRepoRequest;

  try {
    const data = await api.deleteEnvironmentRepo(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **environmentId** | `string` |  | [Defaults to `undefined`] |
| **repositoryId** | `string` | The repository `databaseId`. | [Defaults to `undefined`] |

### Return type

[**EnvironmentItemChangeResponse**](EnvironmentItemChangeResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: Not defined
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | New version minted. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **404** | Resource not found. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## deleteEnvironmentSecretFile

> EnvironmentItemChangeResponse deleteEnvironmentSecretFile(path, environmentId)

Remove one secret file

Removes the secret file at `path`. Mints a new immutable version.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { DeleteEnvironmentSecretFileRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string
    path: path_example,
    // string
    environmentId: 38400000-8cf0-11bd-b23e-10b96e4ef00d,
  } satisfies DeleteEnvironmentSecretFileRequest;

  try {
    const data = await api.deleteEnvironmentSecretFile(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **path** | `string` |  | [Defaults to `undefined`] |
| **environmentId** | `string` |  | [Defaults to `undefined`] |

### Return type

[**EnvironmentItemChangeResponse**](EnvironmentItemChangeResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: Not defined
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | New version minted. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **404** | Resource not found. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## deleteEnvironmentVar

> EnvironmentItemChangeResponse deleteEnvironmentVar(environmentId, key)

Remove one environment variable

Removes a single variable. Mints a new immutable version.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { DeleteEnvironmentVarRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string
    environmentId: 38400000-8cf0-11bd-b23e-10b96e4ef00d,
    // string | Environment variable name.
    key: key_example,
  } satisfies DeleteEnvironmentVarRequest;

  try {
    const data = await api.deleteEnvironmentVar(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **environmentId** | `string` |  | [Defaults to `undefined`] |
| **key** | `string` | Environment variable name. | [Defaults to `undefined`] |

### Return type

[**EnvironmentItemChangeResponse**](EnvironmentItemChangeResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: Not defined
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | New version minted. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **404** | Resource not found. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## deleteNamedSnapshot

> NamedSnapshotDeletedResponse deleteNamedSnapshot(name)

Remove a named snapshot

Remove a named snapshot and release its storage (`box snapshot rm <name>` in the CLI). Boxes already deployed from it are unaffected.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { DeleteNamedSnapshotRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string
    name: name_example,
  } satisfies DeleteNamedSnapshotRequest;

  try {
    const data = await api.deleteNamedSnapshot(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **name** | `string` |  | [Defaults to `undefined`] |

### Return type

[**NamedSnapshotDeletedResponse**](NamedSnapshotDeletedResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: Not defined
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | Removed. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **404** | Resource not found. |  -  |
| **409** | `save_in_progress`: a save under this name is still running. Wait for it to settle before removing it. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## deleteSnapshot

> DeletionOperationResponse deleteSnapshot(snapshotId, xAsciiConfirmDelete)

Permanently delete snapshot data

Accept irreversible background deletion of an unpinned snapshot owned by the authenticated account. Snapshots required by another incremental snapshot or active restore return `409`. Poll the returned operation until `completed`.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { DeleteSnapshotRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string | Snapshot id returned by the snapshot list/latest calls.
    snapshotId: 38400000-8cf0-11bd-b23e-10b96e4ef00d,
    // string | Must exactly equal the target `boxId` or `snapshotId`. A missing or mismatched value returns `409` without accepting deletion.
    xAsciiConfirmDelete: xAsciiConfirmDelete_example,
  } satisfies DeleteSnapshotRequest;

  try {
    const data = await api.deleteSnapshot(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **snapshotId** | `string` | Snapshot id returned by the snapshot list/latest calls. | [Defaults to `undefined`] |
| **xAsciiConfirmDelete** | `string` | Must exactly equal the target `boxId` or `snapshotId`. A missing or mismatched value returns `409` without accepting deletion. | [Defaults to `undefined`] |

### Return type

[**DeletionOperationResponse**](DeletionOperationResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: Not defined
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **202** | Deletion confirmed and accepted for background processing. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **403** | Authenticated token is not allowed to perform this action. |  -  |
| **404** | Resource not found. |  -  |
| **409** | Request conflicts with current account or box state. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## deleteWebhook

> WebhookDeleteResponse deleteWebhook(webhookId)

Delete webhook

Deletes the endpoint and its queued deliveries. An attempt already in flight can still arrive.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { DeleteWebhookRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string
    webhookId: webhookId_example,
  } satisfies DeleteWebhookRequest;

  try {
    const data = await api.deleteWebhook(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **webhookId** | `string` |  | [Defaults to `undefined`] |

### Return type

[**WebhookDeleteResponse**](WebhookDeleteResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: Not defined
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | Webhook deleted. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **404** | Resource not found. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## desktop

> DesktopResponse desktop(boxId, vnc, theme, desktopRequest)

Get desktop streaming URL

Create or fetch a secret-bearing desktop/noVNC URL for live computer-use visibility. Use `?vnc=1` for noVNC; a `provisioning: true` response means poll again.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { DesktopOperationRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string | Public Box id returned by create/list/get box calls.
    boxId: boxId_example,
    // 1 | Use VNC/noVNC streaming mode. (optional)
    vnc: 56,
    // 'light' | 'dark' | Desktop streaming theme for non-VNC mode. (optional)
    theme: theme_example,
    // DesktopRequest (optional)
    desktopRequest: ...,
  } satisfies DesktopOperationRequest;

  try {
    const data = await api.desktop(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **boxId** | `string` | Public Box id returned by create/list/get box calls. | [Defaults to `undefined`] |
| **vnc** | `1` | Use VNC/noVNC streaming mode. | [Optional] [Defaults to `undefined`] [Enum: 1] |
| **theme** | `light`, `dark` | Desktop streaming theme for non-VNC mode. | [Optional] [Defaults to `undefined`] [Enum: light, dark] |
| **desktopRequest** | [DesktopRequest](DesktopRequest.md) |  | [Optional] |

### Return type

[**DesktopResponse**](DesktopResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: `application/json`
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | Desktop streaming URL, or provisioning state for VNC setup. |  -  |
| **400** | Invalid request body or parameters. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **402** | Account cannot currently create or operate Boxes. The error body may include a dashboard billing URL, but billing actions are not part of the v1 API. |  -  |
| **404** | Resource not found. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## environments

> BoxEnvironmentListResponse environments()

List Boat environments

Returns every non-deleted Boat environment with its latest-version flags, contents, and per-version box usage. A default environment named `base` is created on first access if none exists.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { EnvironmentsRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  try {
    const data = await api.environments();
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters

This endpoint does not need any parameter.

### Return type

[**BoxEnvironmentListResponse**](BoxEnvironmentListResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: Not defined
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | The account\'s Boat environments. |  -  |
| **401** | Missing or invalid bearer token. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## events

> EventsResponse events(boxId, limit, cursor, sort, type, conversation)

List box events

Return Boat work, lifecycle, and progress events so product UIs can show what the box is doing. A Box runs many conversations in parallel; this streams **all** of them by default and every event carries a `conversationId`. Filter to one or more with `conversation`. Event payloads are extensible. Clients can long-poll this endpoint with `sort=asc` and a cursor to stream responses. Response events expose agent text, streaming partials via `data.is_streaming`, and tool calls/results via `data.tools`.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { EventsRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string | Public Box id returned by create/list/get box calls.
    boxId: boxId_example,
    // number | Maximum items to return. (optional)
    limit: 56,
    // string | Opaque pagination cursor returned as `pageInfo.nextCursor`. (optional)
    cursor: cursor_example,
    // 'asc' | 'desc' | Sort direction for cursor pagination. (optional)
    sort: sort_example,
    // string | Comma-separated event type filter, for example `prompt,response,steer`. (optional)
    type: type_example,
    // string | Only return events for this conversation id. Repeat the parameter (or comma-separate) for several. Omit to stream every conversation on the Box. See [Integrated agents](/box/integrated-agents). (optional)
    conversation: conversation_example,
  } satisfies EventsRequest;

  try {
    const data = await api.events(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **boxId** | `string` | Public Box id returned by create/list/get box calls. | [Defaults to `undefined`] |
| **limit** | `number` | Maximum items to return. | [Optional] [Defaults to `100`] |
| **cursor** | `string` | Opaque pagination cursor returned as `pageInfo.nextCursor`. | [Optional] [Defaults to `undefined`] |
| **sort** | `asc`, `desc` | Sort direction for cursor pagination. | [Optional] [Defaults to `'desc'`] [Enum: asc, desc] |
| **type** | `string` | Comma-separated event type filter, for example `prompt,response,steer`. | [Optional] [Defaults to `undefined`] |
| **conversation** | `string` | Only return events for this conversation id. Repeat the parameter (or comma-separate) for several. Omit to stream every conversation on the Box. See [Integrated agents](/box/integrated-agents). | [Optional] [Defaults to `undefined`] |

### Return type

[**EventsResponse**](EventsResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: Not defined
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | The agent\'s work on the box (prompts, responses), not box lifecycle. A box that was never prompted returns an empty list even though it started, stopped and resumed. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **402** | Account cannot currently create or operate Boxes. The error body may include a dashboard billing URL, but billing actions are not part of the v1 API. |  -  |
| **404** | Resource not found. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## fork

> BoxActionResponse fork(boxId, idempotencyKey, forkRequest)

Fork box

Provision a new box from an existing one. Send an `Idempotency-Key` header to make this call safe to retry after a lost response without creating a second billable fork.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { ForkOperationRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string | Public Box id returned by create/list/get box calls.
    boxId: boxId_example,
    // string | Optional exactly-once key for creating a box. Send your own opaque, account-unique value (a UUID) to make `POST /boxes` safe to retry when the response is lost (network timeout, 5xx): the first request creates the box and binds it to the key; every later request with the **same account, key, and request body** returns that same box instead of creating a second, billable one. Behavior: keys are retained for **24 hours**; a concurrent or early retry while the first box is still being minted returns `409` `idempotency_in_progress` (retry shortly, same key); reusing a key with a **different body** returns `409` `idempotency_key_reused`; timeouts and 5xx are safe to retry with the same key; a create that fails before the box exists releases the key within ~2 minutes so a retry can create the box. Omit the header to keep the default (non-idempotent) behavior. (optional)
    idempotencyKey: idempotencyKey_example,
    // ForkRequest (optional)
    forkRequest: ...,
  } satisfies ForkOperationRequest;

  try {
    const data = await api.fork(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **boxId** | `string` | Public Box id returned by create/list/get box calls. | [Defaults to `undefined`] |
| **idempotencyKey** | `string` | Optional exactly-once key for creating a box. Send your own opaque, account-unique value (a UUID) to make `POST /boxes` safe to retry when the response is lost (network timeout, 5xx): the first request creates the box and binds it to the key; every later request with the **same account, key, and request body** returns that same box instead of creating a second, billable one. Behavior: keys are retained for **24 hours**; a concurrent or early retry while the first box is still being minted returns `409` `idempotency_in_progress` (retry shortly, same key); reusing a key with a **different body** returns `409` `idempotency_key_reused`; timeouts and 5xx are safe to retry with the same key; a create that fails before the box exists releases the key within ~2 minutes so a retry can create the box. Omit the header to keep the default (non-idempotent) behavior. | [Optional] [Defaults to `undefined`] |
| **forkRequest** | [ForkRequest](ForkRequest.md) |  | [Optional] |

### Return type

[**BoxActionResponse**](BoxActionResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: `application/json`
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **202** | Fork started. The response `id` is the new forked box id. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **402** | Account cannot currently create or operate Boxes. The error body may include a dashboard billing URL, but billing actions are not part of the v1 API. |  -  |
| **404** | Resource not found. |  -  |
| **409** | Request conflicts with current account or box state. |  -  |
| **429** | Machine start or concurrent-box limit reached. Create, fork and resume each count as one machine start against your plan\'s start limits (see the Billing guide; `rate_limited`, naming the window you hit). A box that would exceed your plan\'s concurrent-box cap is refused with `limit_reached`, or `member_limit_reached` when an organization owner has capped you below the plan. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## get

> BoxInfoResponse get(boxId)

Get box

Poll this endpoint after create, stop, resume, or fork operations.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { GetRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string | Public Box id returned by create/list/get box calls.
    boxId: boxId_example,
  } satisfies GetRequest;

  try {
    const data = await api.get(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **boxId** | `string` | Public Box id returned by create/list/get box calls. | [Defaults to `undefined`] |

### Return type

[**BoxInfoResponse**](BoxInfoResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: Not defined
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | Box details. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **404** | Resource not found. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## getDataRetention

> DataRetentionPolicyResponse getDataRetention()

Get account data-retention policy

Returns the current zero-data-retention policy. Per-box API keys cannot access this account-wide setting. Responses are never cached.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { GetDataRetentionRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  try {
    const data = await api.getDataRetention();
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters

This endpoint does not need any parameter.

### Return type

[**DataRetentionPolicyResponse**](DataRetentionPolicyResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: Not defined
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | Current retention policy. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **403** | Authenticated token is not allowed to perform this action. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## getDeletionOperation

> DeletionOperationResponse getDeletionOperation(operationId)

Get deletion operation

Poll an accepted Boat or snapshot deletion. Only operations owned by the authenticated account are returned. Responses are never cached.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { GetDeletionOperationRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string | Deletion operation id returned by an accepted delete request.
    operationId: operationId_example,
  } satisfies GetDeletionOperationRequest;

  try {
    const data = await api.getDeletionOperation(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **operationId** | `string` | Deletion operation id returned by an accepted delete request. | [Defaults to `undefined`] |

### Return type

[**DeletionOperationResponse**](DeletionOperationResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: Not defined
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | Current deletion operation state. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **404** | Resource not found. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## getLatestBoxSnapshot

> SnapshotLatestResponse getLatestBoxSnapshot(boxId)

Get latest box snapshot

Return the most recent completed snapshot for this box, or `null` if it has none.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { GetLatestBoxSnapshotRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string | Public Box id returned by create/list/get box calls.
    boxId: boxId_example,
  } satisfies GetLatestBoxSnapshotRequest;

  try {
    const data = await api.getLatestBoxSnapshot(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **boxId** | `string` | Public Box id returned by create/list/get box calls. | [Defaults to `undefined`] |

### Return type

[**SnapshotLatestResponse**](SnapshotLatestResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: Not defined
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | Most recent completed snapshot, or `null`. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **404** | Resource not found. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## getNamedSnapshot

> NamedSnapshotInfoResponse getNamedSnapshot(name)

Get a named snapshot

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { GetNamedSnapshotRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string
    name: name_example,
  } satisfies GetNamedSnapshotRequest;

  try {
    const data = await api.getNamedSnapshot(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **name** | `string` |  | [Defaults to `undefined`] |

### Return type

[**NamedSnapshotInfoResponse**](NamedSnapshotInfoResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: Not defined
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | The named snapshot. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **404** | Resource not found. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## getSnapshotDownload

> SnapshotDownloadResponse getSnapshotDownload(snapshotId)

Get snapshot download

Return time-limited signed URLs for every chunk needed to reconstruct the box filesystem at this snapshot (the full chain, base through this generation), plus the inventory. Download the chunks and reassemble them as described by `reconstruct`. The `box snapshot pull` CLI command does this for you. 

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { GetSnapshotDownloadRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string | Snapshot id returned by the snapshot list/latest calls.
    snapshotId: 38400000-8cf0-11bd-b23e-10b96e4ef00d,
  } satisfies GetSnapshotDownloadRequest;

  try {
    const data = await api.getSnapshotDownload(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **snapshotId** | `string` | Snapshot id returned by the snapshot list/latest calls. | [Defaults to `undefined`] |

### Return type

[**SnapshotDownloadResponse**](SnapshotDownloadResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: Not defined
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | Signed chunk URLs for the snapshot chain. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **404** | Resource not found. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## getSnapshotFile

> Blob getSnapshotFile(snapshotId, path)

Download a file or folder from a snapshot

Stream a single file\'s bytes, or a folder subtree as a tar archive, directly out of a snapshot, the box can be stopped or archived; the machine is never contacted. Use `GET /snapshots/{snapshotId}/tree` to list paths, then pass one here. Paths are relative to the snapshot root (same space as `tree` entries; docker volumes under `__dockervol__/`). An empty or `/` path downloads the whole snapshot as a tar. Folder responses set `X-Snapshot-File-Count`, `X-Snapshot-Total-Size-Bytes` and `X-Snapshot-Skipped-Base-Image-Files` headers; both response shapes set `X-Snapshot-Entry-Kind` (`file` or `dir`).

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { GetSnapshotFileRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string | Snapshot id returned by the snapshot list/latest calls.
    snapshotId: 38400000-8cf0-11bd-b23e-10b96e4ef00d,
    // string | File or folder path inside the snapshot. Empty for the whole snapshot. (optional)
    path: path_example,
  } satisfies GetSnapshotFileRequest;

  try {
    const data = await api.getSnapshotFile(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **snapshotId** | `string` | Snapshot id returned by the snapshot list/latest calls. | [Defaults to `undefined`] |
| **path** | `string` | File or folder path inside the snapshot. Empty for the whole snapshot. | [Optional] [Defaults to `undefined`] |

### Return type

**Blob**

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: Not defined
- **Accept**: `application/octet-stream`, `application/x-tar`, `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | File bytes (`application/octet-stream`) or folder tar (`application/x-tar`). |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **404** | Resource not found. |  -  |
| **409** | Path has no downloadable bytes, one of `legacy_snapshot` (pre-inventory snapshot), `snapshot_not_indexed` (content captured before the indexed snapshot format; take a new snapshot or use the download bundle), `base_image_file` (stock image file, not stored in snapshots), or `is_symlink` (request the symlink\'s target instead). |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## getSnapshotTree

> SnapshotTreeResponse getSnapshotTree(snapshotId)

Get snapshot file tree

List the files and folders captured in a snapshot, with sizes. Returns a flat list of entries you can render as a tree.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { GetSnapshotTreeRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string | Snapshot id returned by the snapshot list/latest calls.
    snapshotId: 38400000-8cf0-11bd-b23e-10b96e4ef00d,
  } satisfies GetSnapshotTreeRequest;

  try {
    const data = await api.getSnapshotTree(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **snapshotId** | `string` | Snapshot id returned by the snapshot list/latest calls. | [Defaults to `undefined`] |

### Return type

[**SnapshotTreeResponse**](SnapshotTreeResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: Not defined
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | Flat file/folder listing for the snapshot. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **404** | Resource not found. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## getWebhook

> WebhookResponse getWebhook(webhookId)

Get webhook

Returns webhook metadata without the signing secret.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { GetWebhookRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string
    webhookId: webhookId_example,
  } satisfies GetWebhookRequest;

  try {
    const data = await api.getWebhook(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **webhookId** | `string` |  | [Defaults to `undefined`] |

### Return type

[**WebhookResponse**](WebhookResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: Not defined
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | Webhook metadata. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **404** | Resource not found. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## hostPort

> HostPortResponse hostPort(boxId, hostPortRequest)

Expose a box port on a public HTTPS URL

Registers a stable `https://<box-subdomain>-<port>.on.ascii.dev` route for a port inside the Boat and opens the Boat firewall for it. Idempotent: calling it again for the same Boat and port returns the same URL and token.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { HostPortOperationRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string | Public Box id returned by create/list/get box calls.
    boxId: boxId_example,
    // HostPortRequest
    hostPortRequest: ...,
  } satisfies HostPortOperationRequest;

  try {
    const data = await api.hostPort(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **boxId** | `string` | Public Box id returned by create/list/get box calls. | [Defaults to `undefined`] |
| **hostPortRequest** | [HostPortRequest](HostPortRequest.md) |  | |

### Return type

[**HostPortResponse**](HostPortResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: `application/json`
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | The public HTTPS URL for the port. |  -  |
| **400** | Invalid request body or parameters. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **402** | Account cannot currently create or operate Boxes. The error body may include a dashboard billing URL, but billing actions are not part of the v1 API. |  -  |
| **404** | Resource not found. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## interrupt

> BoxActionResponse interrupt(boxId, conversation)

Interrupt running work

Interrupt running agent work. By default this stops **every** conversation on the Box. Pass `conversation` to stop just one, leaving the others running. See [Integrated agents](/box/integrated-agents).

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { InterruptRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string | Public Box id returned by create/list/get box calls.
    boxId: boxId_example,
    // string | Interrupt only this conversation id. Omit to interrupt the whole Box. (optional)
    conversation: conversation_example,
  } satisfies InterruptRequest;

  try {
    const data = await api.interrupt(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **boxId** | `string` | Public Box id returned by create/list/get box calls. | [Defaults to `undefined`] |
| **conversation** | `string` | Interrupt only this conversation id. Omit to interrupt the whole Box. | [Optional] [Defaults to `undefined`] |

### Return type

[**BoxActionResponse**](BoxActionResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: Not defined
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | Interrupt requested. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **402** | Account cannot currently create or operate Boxes. The error body may include a dashboard billing URL, but billing actions are not part of the v1 API. |  -  |
| **404** | Resource not found. |  -  |
| **409** | Request conflicts with current account or box state. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## limits

> LimitsResponse limits(org, xBoxOrg, teamId)

Get Boat limits

Check remaining machine starts, compute time, credits, access readiness, and concurrent-box capacity for the authenticated account. Pass `org` / `X-Box-Org` (or `teamId`) to read a team wallet you belong to.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { LimitsRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string | Billing wallet for this request. A team id you belong to reads that team\'s limits / bills a create to that team. Your own account id is personal. Boxes, snapshots, and environments stay creator-private. (optional)
    org: org_example,
    // string | Same as the `org` query parameter. Query wins when both are set. (optional)
    xBoxOrg: xBoxOrg_example,
    // string | Legacy alias for `org`. Takes precedence over `org` / `X-Box-Org` when set. (optional)
    teamId: teamId_example,
  } satisfies LimitsRequest;

  try {
    const data = await api.limits(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **org** | `string` | Billing wallet for this request. A team id you belong to reads that team\'s limits / bills a create to that team. Your own account id is personal. Boxes, snapshots, and environments stay creator-private. | [Optional] [Defaults to `undefined`] |
| **xBoxOrg** | `string` | Same as the `org` query parameter. Query wins when both are set. | [Optional] [Defaults to `undefined`] |
| **teamId** | `string` | Legacy alias for `org`. Takes precedence over `org` / `X-Box-Org` when set. | [Optional] [Defaults to `undefined`] |

### Return type

[**LimitsResponse**](LimitsResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: Not defined
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | Current creation and concurrent-box limits. |  -  |
| **401** | Missing or invalid bearer token. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## listBoxSnapshots

> SnapshotListResponse listBoxSnapshots(boxId, limit, cursor, sort)

List box snapshots

List visible completed snapshots for one Box with uncapped cursor pagination.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { ListBoxSnapshotsRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string | Public Box id returned by create/list/get box calls.
    boxId: boxId_example,
    // number | Maximum items to return. (optional)
    limit: 56,
    // string | Opaque pagination cursor returned as `pageInfo.nextCursor`. (optional)
    cursor: cursor_example,
    // 'asc' | 'desc' | Sort direction for cursor pagination. (optional)
    sort: sort_example,
  } satisfies ListBoxSnapshotsRequest;

  try {
    const data = await api.listBoxSnapshots(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **boxId** | `string` | Public Box id returned by create/list/get box calls. | [Defaults to `undefined`] |
| **limit** | `number` | Maximum items to return. | [Optional] [Defaults to `100`] |
| **cursor** | `string` | Opaque pagination cursor returned as `pageInfo.nextCursor`. | [Optional] [Defaults to `undefined`] |
| **sort** | `asc`, `desc` | Sort direction for cursor pagination. | [Optional] [Defaults to `'desc'`] [Enum: asc, desc] |

### Return type

[**SnapshotListResponse**](SnapshotListResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: Not defined
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | Completed snapshots for this box. |  -  |
| **400** | Invalid request body or parameters. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **404** | Resource not found. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## listNamedSnapshots

> NamedSnapshotListResponse listNamedSnapshots()

List named snapshots

List your named snapshots, newest first.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { ListNamedSnapshotsRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  try {
    const data = await api.listNamedSnapshots();
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters

This endpoint does not need any parameter.

### Return type

[**NamedSnapshotListResponse**](NamedSnapshotListResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: Not defined
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | Named snapshots owned by the authenticated Boat user. |  -  |
| **401** | Missing or invalid bearer token. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## listSnapshots

> SnapshotListResponse listSnapshots(limit, cursor, sort)

List snapshots

List visible completed snapshots across all of your boxes using immutable ownership attribution. Pinned, deletion-scheduled, and privacy-fenced Box snapshots are omitted. Follow `nextCursor` through the complete history; there is no hidden 500-snapshot cap.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { ListSnapshotsRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // number | Maximum items to return. (optional)
    limit: 56,
    // string | Opaque pagination cursor returned as `pageInfo.nextCursor`. (optional)
    cursor: cursor_example,
    // 'asc' | 'desc' | Sort direction for cursor pagination. (optional)
    sort: sort_example,
  } satisfies ListSnapshotsRequest;

  try {
    const data = await api.listSnapshots(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **limit** | `number` | Maximum items to return. | [Optional] [Defaults to `100`] |
| **cursor** | `string` | Opaque pagination cursor returned as `pageInfo.nextCursor`. | [Optional] [Defaults to `undefined`] |
| **sort** | `asc`, `desc` | Sort direction for cursor pagination. | [Optional] [Defaults to `'desc'`] [Enum: asc, desc] |

### Return type

[**SnapshotListResponse**](SnapshotListResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: Not defined
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | Completed snapshots owned by the authenticated Boat user. |  -  |
| **400** | Invalid request body or parameters. |  -  |
| **401** | Missing or invalid bearer token. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## listWebhooks

> WebhookListResponse listWebhooks()

List webhooks

Lists account-wide Boat lifecycle webhook endpoints. Signing secrets are never included.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { ListWebhooksRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  try {
    const data = await api.listWebhooks();
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters

This endpoint does not need any parameter.

### Return type

[**WebhookListResponse**](WebhookListResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: Not defined
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | Registered webhook endpoints. |  -  |
| **401** | Missing or invalid bearer token. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## me

> MeResponse me()

Get current Boat user

Returns GitHub identity for the authenticated Boat account.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { MeRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  try {
    const data = await api.me();
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters

This endpoint does not need any parameter.

### Return type

[**MeResponse**](MeResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: Not defined
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | Current user information. |  -  |
| **401** | Missing or invalid bearer token. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## prompt

> PromptResponse prompt(boxId, promptRequest)

Prompt Boat

Queue a natural-language work item for an agent harness (Codex, Claude Code, pi, OpenCode, or Prime Agent) inside the box. Observe progress with `GET /boxes/{boxId}/events`.  A Box runs many conversations in parallel. Set `new: true` to start a fresh one, `conversationId` to continue a specific one, or omit both to continue the most-recently-active conversation; the response returns the `conversationId`. See [Integrated agents](/box/integrated-agents).

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { PromptOperationRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string | Public Box id returned by create/list/get box calls.
    boxId: boxId_example,
    // PromptRequest
    promptRequest: {"provider":"codex","model":"gpt-5.4","reasoningEffort":"medium","prompt":"Work on the selected repo, run tests, fix failures, commit the result, and report any hosted preview URL."},
  } satisfies PromptOperationRequest;

  try {
    const data = await api.prompt(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **boxId** | `string` | Public Box id returned by create/list/get box calls. | [Defaults to `undefined`] |
| **promptRequest** | [PromptRequest](PromptRequest.md) |  | |

### Return type

[**PromptResponse**](PromptResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: `application/json`
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **202** | Prompt queued. |  -  |
| **400** | Invalid request body or parameters. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **402** | Account cannot currently create or operate Boxes. The error body may include a dashboard billing URL, but billing actions are not part of the v1 API. |  -  |
| **404** | Resource not found. |  -  |
| **409** | Request conflicts with current account or box state. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## promptRunStatus

> PromptRunResponse promptRunStatus(boxId, promptId)

Get prompt run status

Returns first-class status for a queued/running/finished prompt so clients do not infer completion from box state and events.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { PromptRunStatusRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string | Public Box id returned by create/list/get box calls.
    boxId: boxId_example,
    // string
    promptId: promptId_example,
  } satisfies PromptRunStatusRequest;

  try {
    const data = await api.promptRunStatus(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **boxId** | `string` | Public Box id returned by create/list/get box calls. | [Defaults to `undefined`] |
| **promptId** | `string` |  | [Defaults to `undefined`] |

### Return type

[**PromptRunResponse**](PromptRunResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: Not defined
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | Prompt run status. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **404** | Resource not found. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## readFile

> FileReadResponse readFile(boxId, path, encoding)

Read a file from a Boat

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { ReadFileRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string | Public Box id returned by create/list/get box calls.
    boxId: boxId_example,
    // string
    path: path_example,
    // 'utf8' | 'base64' (optional)
    encoding: encoding_example,
  } satisfies ReadFileRequest;

  try {
    const data = await api.readFile(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **boxId** | `string` | Public Box id returned by create/list/get box calls. | [Defaults to `undefined`] |
| **path** | `string` |  | [Defaults to `undefined`] |
| **encoding** | `utf8`, `base64` |  | [Optional] [Defaults to `'utf8'`] [Enum: utf8, base64] |

### Return type

[**FileReadResponse**](FileReadResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: Not defined
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | File contents. |  -  |
| **400** | Invalid request body or parameters. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## repos

> ReposResponse repos(sync, limit, cursor, sort, q, selected)

List GitHub repositories available to Boat

Returns GitHub repositories grouped by installation plus the current selected repositories for new Boxes.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { ReposRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // boolean | When true, sync from GitHub before returning repository groups. (optional)
    sync: true,
    // number | Maximum items to return. (optional)
    limit: 56,
    // string | Opaque pagination cursor returned as `pageInfo.nextCursor`. (optional)
    cursor: cursor_example,
    // 'asc' | 'desc' | Sort direction for cursor pagination. (optional)
    sort: sort_example,
    // string | Case-insensitive repository name/fullName filter. (optional)
    q: q_example,
    // boolean | Filter to selected or unselected repositories. (optional)
    selected: true,
  } satisfies ReposRequest;

  try {
    const data = await api.repos(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **sync** | `boolean` | When true, sync from GitHub before returning repository groups. | [Optional] [Defaults to `undefined`] |
| **limit** | `number` | Maximum items to return. | [Optional] [Defaults to `100`] |
| **cursor** | `string` | Opaque pagination cursor returned as `pageInfo.nextCursor`. | [Optional] [Defaults to `undefined`] |
| **sort** | `asc`, `desc` | Sort direction for cursor pagination. | [Optional] [Defaults to `'desc'`] [Enum: asc, desc] |
| **q** | `string` | Case-insensitive repository name/fullName filter. | [Optional] [Defaults to `undefined`] |
| **selected** | `boolean` | Filter to selected or unselected repositories. | [Optional] [Defaults to `undefined`] |

### Return type

[**ReposResponse**](ReposResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: Not defined
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | Repository groups and current Boat repository selection. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **409** | Request conflicts with current account or box state. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## resume

> BoxActionResponse resume(boxId, resumeRequest)

Resume box

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { ResumeOperationRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string | Public Box id returned by create/list/get box calls.
    boxId: boxId_example,
    // ResumeRequest (optional)
    resumeRequest: ...,
  } satisfies ResumeOperationRequest;

  try {
    const data = await api.resume(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **boxId** | `string` | Public Box id returned by create/list/get box calls. | [Defaults to `undefined`] |
| **resumeRequest** | [ResumeRequest](ResumeRequest.md) |  | [Optional] |

### Return type

[**BoxActionResponse**](BoxActionResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: `application/json`
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **202** | Resume started. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **402** | Account cannot currently create or operate Boxes. The error body may include a dashboard billing URL, but billing actions are not part of the v1 API. |  -  |
| **404** | Resource not found. |  -  |
| **409** | Request conflicts with current account or box state. |  -  |
| **429** | Machine start or concurrent-box limit reached. Create, fork and resume each count as one machine start against your plan\'s start limits (see the Billing guide; `rate_limited`, naming the window you hit). A box that would exceed your plan\'s concurrent-box cap is refused with `limit_reached`, or `member_limit_reached` when an organization owner has capped you below the plan. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## revokeApiKey

> ApiKeyRevokeResponse revokeApiKey(apiKeyId)

Revoke an API key

Revokes the key immediately. Requires a dashboard or CLI session.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { RevokeApiKeyRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string
    apiKeyId: apiKeyId_example,
  } satisfies RevokeApiKeyRequest;

  try {
    const data = await api.revokeApiKey(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **apiKeyId** | `string` |  | [Defaults to `undefined`] |

### Return type

[**ApiKeyRevokeResponse**](ApiKeyRevokeResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: Not defined
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | Key revoked. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **403** | Authenticated token is not allowed to perform this action. |  -  |
| **404** | Resource not found. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## rotateApiKey

> ApiKeySecretResponse rotateApiKey(apiKeyId)

Rotate an API key

Replaces the raw secret without changing expiry or scope. Requires a dashboard or CLI session.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { RotateApiKeyRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string
    apiKeyId: apiKeyId_example,
  } satisfies RotateApiKeyRequest;

  try {
    const data = await api.rotateApiKey(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **apiKeyId** | `string` |  | [Defaults to `undefined`] |

### Return type

[**ApiKeySecretResponse**](ApiKeySecretResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: Not defined
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | Rotated key metadata plus the one-time replacement secret. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **403** | Authenticated token is not allowed to perform this action. |  -  |
| **404** | Resource not found. |  -  |
| **409** | The scoped API key has already expired and cannot be rotated. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## rotateWebhookSigningSecret

> WebhookSecretResponse rotateWebhookSigningSecret(webhookId)

Rotate webhook signing secret

Replaces the endpoint\'s signing secret. The new secret is returned only in this response; briefly accept the old secret for attempts already in flight.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { RotateWebhookSigningSecretRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string
    webhookId: webhookId_example,
  } satisfies RotateWebhookSigningSecretRequest;

  try {
    const data = await api.rotateWebhookSigningSecret(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **webhookId** | `string` |  | [Defaults to `undefined`] |

### Return type

[**WebhookSecretResponse**](WebhookSecretResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: Not defined
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | Signing secret rotated. Store the new secret now. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **404** | Resource not found. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## saveNamedSnapshot

> NamedSnapshotSavingResponse saveNamedSnapshot(namedSnapshotSaveRequest)

Save a named snapshot

Freeze a box\'s current state under a name (`box snapshot <id> <name>` in the CLI). Answers `202` immediately with the snapshot in `saving`; a running box takes a fresh capture first, which can run minutes. Poll `GET /named-snapshots/{name}` until the status settles at `ready` or `failed`. Reusing one of your existing names replaces that snapshot\'s artifact once the new save is ready.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { SaveNamedSnapshotRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // NamedSnapshotSaveRequest
    namedSnapshotSaveRequest: ...,
  } satisfies SaveNamedSnapshotRequest;

  try {
    const data = await api.saveNamedSnapshot(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **namedSnapshotSaveRequest** | [NamedSnapshotSaveRequest](NamedSnapshotSaveRequest.md) |  | |

### Return type

[**NamedSnapshotSavingResponse**](NamedSnapshotSavingResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: `application/json`
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **202** | Save accepted and running in the background. |  -  |
| **400** | Invalid request body or parameters. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **404** | Resource not found. |  -  |
| **409** | `named_snapshot_limit` when you already keep the maximum of 10 named snapshots; remove one first. `save_in_progress` when a save under this name is already running; wait for it to settle rather than retrying immediately. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## secrets

> SecretsResponse secrets()

Get Boat secrets setup

Returns the environment variables and secret files configured for Boxes.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { SecretsRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  try {
    const data = await api.secrets();
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters

This endpoint does not need any parameter.

### Return type

[**SecretsResponse**](SecretsResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: Not defined
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | Current secret setup metadata. |  -  |
| **401** | Missing or invalid bearer token. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## selectRepo

> RepoSelectionResponse selectRepo(repoSelectionRequest)

Select repository for boxes

Idempotently selects one repository for the Boat environment. Use `databaseId` from `GET /repos` as `repositoryId`; selecting an already-selected repository updates its `baseBranch`.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { SelectRepoRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // RepoSelectionRequest
    repoSelectionRequest: ...,
  } satisfies SelectRepoRequest;

  try {
    const data = await api.selectRepo(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **repoSelectionRequest** | [RepoSelectionRequest](RepoSelectionRequest.md) |  | |

### Return type

[**RepoSelectionResponse**](RepoSelectionResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: `application/json`
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | Updated repository selection. |  -  |
| **400** | Invalid request body or parameters. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **409** | Request conflicts with current account or box state. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## setEnvironmentSecretFile

> EnvironmentItemChangeResponse setEnvironmentSecretFile(environmentId, setEnvironmentSecretFileRequest)

Write one secret file

Adds or replaces a single secret file by path. Mints a new immutable version.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { SetEnvironmentSecretFileOperationRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string
    environmentId: 38400000-8cf0-11bd-b23e-10b96e4ef00d,
    // SetEnvironmentSecretFileRequest
    setEnvironmentSecretFileRequest: ...,
  } satisfies SetEnvironmentSecretFileOperationRequest;

  try {
    const data = await api.setEnvironmentSecretFile(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **environmentId** | `string` |  | [Defaults to `undefined`] |
| **setEnvironmentSecretFileRequest** | [SetEnvironmentSecretFileRequest](SetEnvironmentSecretFileRequest.md) |  | |

### Return type

[**EnvironmentItemChangeResponse**](EnvironmentItemChangeResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: `application/json`
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | New version minted. |  -  |
| **400** | Invalid request body or parameters. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **404** | Resource not found. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## setEnvironmentVar

> EnvironmentItemChangeResponse setEnvironmentVar(environmentId, key, setEnvironmentVarRequest)

Set one environment variable

Sets or replaces a single variable without reading or rewriting the rest. Mints a new immutable version.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { SetEnvironmentVarOperationRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string
    environmentId: 38400000-8cf0-11bd-b23e-10b96e4ef00d,
    // string | Environment variable name.
    key: key_example,
    // SetEnvironmentVarRequest
    setEnvironmentVarRequest: ...,
  } satisfies SetEnvironmentVarOperationRequest;

  try {
    const data = await api.setEnvironmentVar(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **environmentId** | `string` |  | [Defaults to `undefined`] |
| **key** | `string` | Environment variable name. | [Defaults to `undefined`] |
| **setEnvironmentVarRequest** | [SetEnvironmentVarRequest](SetEnvironmentVarRequest.md) |  | |

### Return type

[**EnvironmentItemChangeResponse**](EnvironmentItemChangeResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: `application/json`
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | New version minted. |  -  |
| **400** | Invalid request body or parameters. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **404** | Resource not found. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## sshKey

> SshKeyResponse sshKey(boxId, sshKeyRequest)

Configure box SSH key

Adds an OpenSSH public key to the running Boat so the caller can SSH as user `user`. The response carries `machineIp`, which is the host to connect to on port 22.  This is also how you reach your own machine from inside a Box without the CLI: authorize the key, then open a reverse tunnel with stock OpenSSH, and a port on your machine answers at `127.0.0.1:<port>` inside the Box for as long as the ssh process runs.  ```bash ssh -o ExitOnForwardFailure=yes -i ~/.ssh/id_ed25519 -N -R 7777:127.0.0.1:7777 user@<machineIp> ```  `box forward <id> --reverse --local 7777` is the same tunnel with the key handling and redial done for you. 

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { SshKeyOperationRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string | Public Box id returned by create/list/get box calls.
    boxId: boxId_example,
    // SshKeyRequest
    sshKeyRequest: ...,
  } satisfies SshKeyOperationRequest;

  try {
    const data = await api.sshKey(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **boxId** | `string` | Public Box id returned by create/list/get box calls. | [Defaults to `undefined`] |
| **sshKeyRequest** | [SshKeyRequest](SshKeyRequest.md) |  | |

### Return type

[**SshKeyResponse**](SshKeyResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: `application/json`
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | SSH key setup result. |  -  |
| **400** | Invalid request body or parameters. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **402** | Account cannot currently create or operate Boxes. The error body may include a dashboard billing URL, but billing actions are not part of the v1 API. |  -  |
| **404** | Resource not found. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## steer

> SteerResponse steer(boxId, steerRequest, conversation)

Steer a running turn

Send a new message to a turn that is already running, without losing what the agent is doing. This is what typing into a coding agent while it works does: the instruction is taken into account and the work continues.  Where the harness has a native mid-turn primitive (Claude Code, Codex, pi, Prime Agent) nothing is interrupted and the response has `native: true`. Where it does not (OpenCode), Box interrupts that turn and immediately continues the SAME conversation with the instruction, keeping the session and its memory, and the response has `native: false`.  Refused with **409 `no_running_turn`** when the conversation has nothing in flight; queue work with `POST /prompt` instead. The steer shows up in `GET /events` as a `steer` event. See [Integrated agents](/box/integrated-agents).

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { SteerOperationRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string | Public Box id returned by create/list/get box calls.
    boxId: boxId_example,
    // SteerRequest
    steerRequest: {"message":"Also write /home/user/steered.txt containing the word STEERED, then finish."},
    // string | Conversation id to steer. Also accepted in the body. Omit to steer the Box\'s most-recently-active conversation. (optional)
    conversation: conversation_example,
  } satisfies SteerOperationRequest;

  try {
    const data = await api.steer(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **boxId** | `string` | Public Box id returned by create/list/get box calls. | [Defaults to `undefined`] |
| **steerRequest** | [SteerRequest](SteerRequest.md) |  | |
| **conversation** | `string` | Conversation id to steer. Also accepted in the body. Omit to steer the Box\'s most-recently-active conversation. | [Optional] [Defaults to `undefined`] |

### Return type

[**SteerResponse**](SteerResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: `application/json`
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | Message delivered to the running turn. |  -  |
| **400** | Invalid request body or parameters. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **402** | Account cannot currently create or operate Boxes. The error body may include a dashboard billing URL, but billing actions are not part of the v1 API. |  -  |
| **404** | Resource not found. |  -  |
| **409** | Request conflicts with current account or box state. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## stop

> BoxActionResponse stop(boxId, stopRequest)

Stop and archive box

Stop active work and archive/snapshot the box for later resume or fork.  A stop always saves the box\'s disk first. If that save is failing, the stop is refused and the box keeps running so your work is not discarded, we retry automatically and email you. You are not billed for time spent in that state.  Set `force: true` to stop anyway, accepting the loss of everything written since the last successful snapshot. This is irreversible; only reach for it after a stop has already failed. 

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { StopOperationRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string | Public Box id returned by create/list/get box calls.
    boxId: boxId_example,
    // StopRequest (optional)
    stopRequest: ...,
  } satisfies StopOperationRequest;

  try {
    const data = await api.stop(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **boxId** | `string` | Public Box id returned by create/list/get box calls. | [Defaults to `undefined`] |
| **stopRequest** | [StopRequest](StopRequest.md) |  | [Optional] |

### Return type

[**BoxActionResponse**](BoxActionResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: `application/json`
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **202** | Box archival started or already in progress. |  -  |
| **400** | Invalid request body or parameters. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **404** | Resource not found. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## update

> BoxInfoResponse update(boxId, updateBoxRequest)

Update box

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { UpdateRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string | Public Box id returned by create/list/get box calls.
    boxId: boxId_example,
    // UpdateBoxRequest
    updateBoxRequest: ...,
  } satisfies UpdateRequest;

  try {
    const data = await api.update(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **boxId** | `string` | Public Box id returned by create/list/get box calls. | [Defaults to `undefined`] |
| **updateBoxRequest** | [UpdateBoxRequest](UpdateBoxRequest.md) |  | |

### Return type

[**BoxInfoResponse**](BoxInfoResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: `application/json`
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | Updated box details. |  -  |
| **400** | Invalid request body or parameters. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **404** | Resource not found. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## updateDataRetention

> DataRetentionPolicyResponse updateDataRetention(dataRetentionUpdateRequest)

Update account data-retention policy

Requires an interactive Boat session; API keys and legacy permanent tokens are refused. Enabling requires the exact confirmation phrase `delete archived box data`. Disabling affects future archives only and cannot cancel deletion operations already accepted.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { UpdateDataRetentionRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // DataRetentionUpdateRequest
    dataRetentionUpdateRequest: ...,
  } satisfies UpdateDataRetentionRequest;

  try {
    const data = await api.updateDataRetention(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **dataRetentionUpdateRequest** | [DataRetentionUpdateRequest](DataRetentionUpdateRequest.md) |  | |

### Return type

[**DataRetentionPolicyResponse**](DataRetentionPolicyResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: `application/json`
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | Updated retention policy. Responses are never cached. |  -  |
| **400** | Invalid request body or parameters. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **403** | Authenticated token is not allowed to perform this action. |  -  |
| **409** | Request conflicts with current account or box state. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## updateEnvironment

> BoxEnvironmentResponse updateEnvironment(environmentId, updateBoxEnvironmentRequest)

Update a Boat environment

Rename, set as default, and/or edit flags and contents. Any flag or content change mints a new immutable version; existing boxes stay on their pinned version until you call upgrade.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { UpdateEnvironmentRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string | Environment id returned by `GET /environments`.
    environmentId: 38400000-8cf0-11bd-b23e-10b96e4ef00d,
    // UpdateBoxEnvironmentRequest
    updateBoxEnvironmentRequest: ...,
  } satisfies UpdateEnvironmentRequest;

  try {
    const data = await api.updateEnvironment(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **environmentId** | `string` | Environment id returned by `GET /environments`. | [Defaults to `undefined`] |
| **updateBoxEnvironmentRequest** | [UpdateBoxEnvironmentRequest](UpdateBoxEnvironmentRequest.md) |  | |

### Return type

[**BoxEnvironmentResponse**](BoxEnvironmentResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: `application/json`
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | Updated environment. |  -  |
| **400** | Invalid request body or parameters. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **404** | Resource not found. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## updateSecrets

> SecretsResponse updateSecrets(secretsUpdateRequest)

Update Boat secrets setup

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { UpdateSecretsRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // SecretsUpdateRequest
    secretsUpdateRequest: ...,
  } satisfies UpdateSecretsRequest;

  try {
    const data = await api.updateSecrets(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **secretsUpdateRequest** | [SecretsUpdateRequest](SecretsUpdateRequest.md) |  | |

### Return type

[**SecretsResponse**](SecretsResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: `application/json`
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | Updated secret setup metadata. |  -  |
| **401** | Missing or invalid bearer token. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## updateWebhook

> WebhookResponse updateWebhook(webhookId, webhookUpdateRequest)

Update webhook

Updates the name, endpoint URL, or subscribed events without changing the signing secret.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { UpdateWebhookRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string
    webhookId: webhookId_example,
    // WebhookUpdateRequest
    webhookUpdateRequest: ...,
  } satisfies UpdateWebhookRequest;

  try {
    const data = await api.updateWebhook(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **webhookId** | `string` |  | [Defaults to `undefined`] |
| **webhookUpdateRequest** | [WebhookUpdateRequest](WebhookUpdateRequest.md) |  | |

### Return type

[**WebhookResponse**](WebhookResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: `application/json`
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | Updated webhook metadata. |  -  |
| **400** | Invalid request body or parameters. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **404** | Resource not found. |  -  |
| **409** | Request conflicts with current account or box state. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## upgradeEnvironment

> UpgradeBoxEnvironmentResponse upgradeEnvironment(environmentId, upgradeBoxEnvironmentRequest)

Upgrade boxes to an environment\'s latest version

Repoints the caller\'s active boxes from an older version of this environment to its latest version, scrubbing any owner secrets the new version drops and hot-pushing the new config.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { UpgradeEnvironmentRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string
    environmentId: 38400000-8cf0-11bd-b23e-10b96e4ef00d,
    // UpgradeBoxEnvironmentRequest (optional)
    upgradeBoxEnvironmentRequest: ...,
  } satisfies UpgradeEnvironmentRequest;

  try {
    const data = await api.upgradeEnvironment(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **environmentId** | `string` |  | [Defaults to `undefined`] |
| **upgradeBoxEnvironmentRequest** | [UpgradeBoxEnvironmentRequest](UpgradeBoxEnvironmentRequest.md) |  | [Optional] |

### Return type

[**UpgradeBoxEnvironmentResponse**](UpgradeBoxEnvironmentResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: `application/json`
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | Upgrade result counts. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **404** | Resource not found. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## usage

> BoxUsageResponse usage(boxId, since, until)

Get box usage

Machine time one box consumed, and what it costs, so you can bill your own users per box. Same meter as `GET /limits`: billable seconds with the box type\'s multiplier applied, paused past a refused stop, never counting time stopped. Narrow it to a billing period with `since` and `until`; a period boundary that falls inside a running stretch splits that stretch pro rata. Works while the box runs and after it stops.

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { UsageRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string | Public Box id returned by create/list/get box calls.
    boxId: boxId_example,
    // string | Count from this time, ISO 8601 or Unix epoch seconds. Default is the box\'s creation. (optional)
    since: 2026-09-01T00:00:00Z,
    // string | Count up to this time, ISO 8601 or Unix epoch seconds. Default is now. (optional)
    until: 2026-10-01T00:00:00Z,
  } satisfies UsageRequest;

  try {
    const data = await api.usage(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **boxId** | `string` | Public Box id returned by create/list/get box calls. | [Defaults to `undefined`] |
| **since** | `string` | Count from this time, ISO 8601 or Unix epoch seconds. Default is the box\'s creation. | [Optional] [Defaults to `undefined`] |
| **until** | `string` | Count up to this time, ISO 8601 or Unix epoch seconds. Default is now. | [Optional] [Defaults to `undefined`] |

### Return type

[**BoxUsageResponse**](BoxUsageResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: Not defined
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | Billable machine time for the box inside the window. |  -  |
| **400** | Invalid request body or parameters. |  -  |
| **401** | Missing or invalid bearer token. |  -  |
| **404** | Resource not found. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)


## writeFile

> FileWriteResponse writeFile(boxId, fileWriteRequest)

Write a file in a Boat

### Example

```ts
import {
  Configuration,
  BoxApi,
} from '@asciidev/box-sdk';
import type { WriteFileRequest } from '@asciidev/box-sdk';

async function example() {
  console.log("🚀 Testing @asciidev/box-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: BoxBearerAuth
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new BoxApi(config);

  const body = {
    // string | Public Box id returned by create/list/get box calls.
    boxId: boxId_example,
    // FileWriteRequest
    fileWriteRequest: ...,
  } satisfies WriteFileRequest;

  try {
    const data = await api.writeFile(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);
```

### Parameters


| Name | Type | Description  | Notes |
|------------- | ------------- | ------------- | -------------|
| **boxId** | `string` | Public Box id returned by create/list/get box calls. | [Defaults to `undefined`] |
| **fileWriteRequest** | [FileWriteRequest](FileWriteRequest.md) |  | |

### Return type

[**FileWriteResponse**](FileWriteResponse.md)

### Authorization

[BoxBearerAuth](../README.md#BoxBearerAuth)

### HTTP request headers

- **Content-Type**: `application/json`
- **Accept**: `application/json`


### HTTP response details
| Status code | Description | Response headers |
|-------------|-------------|------------------|
| **200** | File written. |  -  |
| **400** | Invalid request body or parameters. |  -  |

[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)