Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .codegen.json
Original file line number Diff line number Diff line change
@@ -1 +1 @@
{ "engineHash": "0eab570", "specHash": "7f8494a", "version": "5.20.0" }
{ "engineHash": "dabe8ed", "specHash": "7cec401", "version": "5.20.0" }
1 change: 1 addition & 0 deletions docs/sdkgen/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ General explanations of the available functionality and examples of how to use
the SDK are available by topic:

* [Ai](ai.md)
* [Aisessions](aisessions.md)
* [Aistudio](aistudio.md)
* [Appitemassociations](appitemassociations.md)
* [Archives](archives.md)
Expand Down
74 changes: 74 additions & 0 deletions docs/sdkgen/aisessions.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
# AiSessionsManager


- [List AI sessions](#list-ai-sessions)
- [Delete AI session](#delete-ai-session)

## List AI sessions

Returns a marker-paginated list of the AI sessions that the authenticated
user can read and that were created through the Box public API. Entries are
ordered by `sort` and `direction`, defaulting to `updated_at` descending so
the most recently active session appears first.

The access token must have both the `ai.readwrite` and `root_readwrite`
scopes.

A page may contain fewer than `limit` entries while further pages remain.
Treat a non-null `next_marker` as the only signal that more results exist.

This operation is performed by calling function `getAiSessionsV2026R0`.

See the endpoint docs at
[API Reference](https://developer.box.com/reference/v2026.0/get-ai-sessions/).

*Currently we don't have an example for calling `getAiSessionsV2026R0` in integration tests*

### Arguments

- queryParams `GetAiSessionsV2026R0QueryParams`
- Query parameters of getAiSessionsV2026R0 method
- headers `GetAiSessionsV2026R0Headers`
- Headers of getAiSessionsV2026R0 method


### Returns

This function returns a value of type `AiSessionsV2026R0`.

Returns a paginated list of AI sessions.


## Delete AI session

Deletes an AI session created through the Box public API, together with its
agent tasks. The session's agent-generated files and uploaded files are
moved to the trash. Files attached as sources from elsewhere in Box are not
affected. Deleting a session does not stop a running task or notify the
agent.

The access token must have both the `ai.readwrite` and `root_readwrite`
scopes.

This operation is performed by calling function `deleteAiSessionByIdV2026R0`.

See the endpoint docs at
[API Reference](https://developer.box.com/reference/v2026.0/delete-ai-sessions-id/).

*Currently we don't have an example for calling `deleteAiSessionByIdV2026R0` in integration tests*

### Arguments

- aiSessionId `String`
- The unique identifier of the AI session. This is the same value returned as `id` by the list endpoint and used as the A2A `contextId`. Example: "23489723"
- headers `DeleteAiSessionByIdV2026R0Headers`
- Headers of deleteAiSessionByIdV2026R0 method


### Returns

This function returns a value of type `void`.

Returns an empty response when the AI session was successfully deleted.


2 changes: 2 additions & 0 deletions docs/sdkgen/client.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,8 @@ This method allows you to make any HTTP request to the Box API. It will automati
network configuration settings from the client.
The method accepts a `FetchOptions` object as an argument and returns a `FetchResponse` object.

For request bodies that cannot be safely replayed, such as a JWT assertion with a one-time `jti`, `FetchOptions` also accepts `dataFactory`. `dataFactory.create()` is called on the first attempt when `data` is not set and on each retry so each retry can send a fresh body.

## JSON request

The following example demonstrates how to make a custom POST request to create a new folder in the root folder.
Expand Down
67 changes: 67 additions & 0 deletions docs/sdkgen/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,9 @@
- [Example Delays (with default settings)](#example-delays-with-default-settings)
- [Retry-After Header](#retry-after-header)
- [Network Exception Handling](#network-exception-handling)
- [Retrying Uploads](#retrying-uploads)
- [Streams That Can Be Retried](#streams-that-can-be-retried)
- [Handling Errors for Streams That Cannot Be Retried](#handling-errors-for-streams-that-cannot-be-retried)
- [Customizing Retry Parameters](#customizing-retry-parameters)
- [Custom Retry Strategy](#custom-retry-strategy)
- [Timeouts](#timeouts)
Expand Down Expand Up @@ -129,6 +132,70 @@ This means:
- Network exception retries are tracked independently from HTTP error retries, each with their own counter and backoff progression.
- A request can fail up to `maxRetriesOnException` times due to network exceptions, but each exception retry also increments the overall attempt counter, so the total number of retries across both exception and HTTP error types is bounded by `maxAttempts`.

### Retrying Uploads

To retry a request that uploads content, the SDK has to send the content again. The SDK does not copy the content into memory to do that. Instead, it rewinds the `InputStream` you passed to the position it had when the upload started. Whether the request can be retried therefore depends on the type of the stream.

| Stream type | Retried automatically | How the content is sent again |
| ------------------------------------------------------------------------------------------------------- | --------------------- | -------------------------------------------------------------------------- |
| `FileInputStream` | Yes | The file position is moved back to where it was when the upload started. |
| `ByteArrayInputStream` | Yes | The stream is reset to where it was when the upload started. |
| Any other stream, for example from `Files.newInputStream`, `BufferedInputStream`, or a network response | No | The content is sent once. If that attempt fails, the SDK throws the error. |

If a request with a stream that cannot be rewound fails with a retryable error, such as `429 Too Many Requests` or a `5xx` status, the SDK does not retry it. It throws the original `BoxAPIError` instead, which keeps the response status and headers, including `Retry-After`. For a `401` response, the SDK still refreshes the access token, so your next request uses a valid token.

Uploads to an upload session, such as `uploadBigFile` and `uploadFilePart`, are always retried. Each part is read into memory before it is sent, so it can be sent again regardless of the stream type.

The SDK closes the stream you pass after the request finishes, including all retries, whether it succeeds or fails. Closing it yourself as well, for example with try-with-resources, is safe.

Interceptors run before every attempt, but a request body that reads a stream is built on the first attempt and reused on retries. Changes an interceptor makes to the upload stream on a retry are therefore not applied.

#### Streams That Can Be Retried

To let the SDK retry uploads automatically, pass a `FileInputStream` when uploading from a file:

```java
try (FileInputStream fileStream = new FileInputStream(new File("report.pdf"))) {
client.getUploads().uploadFile(
new UploadFileRequestBody(
new UploadFileRequestBodyAttributesField(
"report.pdf", new UploadFileRequestBodyAttributesParentField("0")),
fileStream));
}
```

If you open files with `Files.newInputStream(path)`, use `new FileInputStream(path.toFile())` instead. The stream returned by `Files.newInputStream` cannot be rewound.

For content that is already in memory, wrap it in a `ByteArrayInputStream`. Do not copy large files into memory only to make them retryable; use a `FileInputStream` instead.

#### Handling Errors for Streams That Cannot Be Retried

If you upload from a stream that cannot be rewound, handle retryable errors in your code and send a new stream on each attempt:

```java
BoxAPIError lastError = null;
for (int attempt = 0; attempt < 3; attempt++) {
try (InputStream stream = openContentStream()) {
return client.getUploads().uploadFile(
new UploadFileRequestBody(
new UploadFileRequestBodyAttributesField(
"report.pdf", new UploadFileRequestBodyAttributesParentField("0")),
stream));
} catch (BoxAPIError error) {
int status = error.getResponseInfo().getStatusCode();
if (status != 429 && status < 500) {
throw error;
}
lastError = error;
String retryAfter = error.getResponseInfo().getHeaders().get("Retry-After");
Thread.sleep(retryAfter != null ? (long) (Double.parseDouble(retryAfter) * 1000) : 1000L);
}
}
throw lastError;
```

`openContentStream()` stands for your own code that opens the content from the beginning, for example a new request to the system the content comes from.

### Customizing Retry Parameters

You can customize all retry parameters by initializing `BoxRetryStrategy` with the desired values and passing it to `NetworkSession`:
Expand Down
Loading
Loading