docs(api): clarify file_batches usage in vector stores files and file batches

stainless-app[bot] · stainless-app[bot] · commit a9cfa713185a · 2026-04-08T21:05:51.000Z
diff --git a/.stats.yml b/.stats.yml
@@ -1,4 +1,4 @@
 configured_endpoints: 151
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-00994178cc8e20d71754b00c54b0e4f5b4128e1c1cce765e9b7d696bd8c80d33.yml
-openapi_spec_hash: 81f404053b663f987209b4fb2d08a230
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-24647ccd7356fee965aaca347476460727c6aec762e16a9eb41950d6fbccf0be.yml
+openapi_spec_hash: ef99e305f20ae8ae7b2758a205280cca
 config_hash: 5635033cdc8c930255f8b529a78de722
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/vectorstores/filebatches/FileBatchCreateParams.kt b/openai-java-core/src/main/kotlin/com/openai/models/vectorstores/filebatches/FileBatchCreateParams.kt
@@ -61,7 +61,8 @@ private constructor(
      * A list of [File](https://platform.openai.com/docs/api-reference/files) IDs that the vector
      * store should use. Useful for tools like `file_search` that can access files. If `attributes`
      * or `chunking_strategy` are provided, they will be applied to all files in the batch. The
-     * maximum batch size is 2000 files. Mutually exclusive with `files`.
+     * maximum batch size is 2000 files. This endpoint is recommended for multi-file ingestion and
+     * helps reduce per-vector-store write request pressure. Mutually exclusive with `files`.
      *
      * @throws OpenAIInvalidDataException if the JSON field has an unexpected type (e.g. if the
      *   server responded with an unexpected value).
@@ -72,7 +73,9 @@ private constructor(
      * A list of objects that each include a `file_id` plus optional `attributes` or
      * `chunking_strategy`. Use this when you need to override metadata for specific files. The
      * global `attributes` or `chunking_strategy` will be ignored and must be specified for each
-     * file. The maximum batch size is 2000 files. Mutually exclusive with `file_ids`.
+     * file. The maximum batch size is 2000 files. This endpoint is recommended for multi-file
+     * ingestion and helps reduce per-vector-store write request pressure. Mutually exclusive with
+     * `file_ids`.
      *
      * @throws OpenAIInvalidDataException if the JSON field has an unexpected type (e.g. if the
      *   server responded with an unexpected value).
@@ -228,7 +231,9 @@ private constructor(
          * A list of [File](https://platform.openai.com/docs/api-reference/files) IDs that the
          * vector store should use. Useful for tools like `file_search` that can access files. If
          * `attributes` or `chunking_strategy` are provided, they will be applied to all files in
-         * the batch. The maximum batch size is 2000 files. Mutually exclusive with `files`.
+         * the batch. The maximum batch size is 2000 files. This endpoint is recommended for
+         * multi-file ingestion and helps reduce per-vector-store write request pressure. Mutually
+         * exclusive with `files`.
          */
         fun fileIds(fileIds: List<String>) = apply { body.fileIds(fileIds) }
 
@@ -252,7 +257,9 @@ private constructor(
          * A list of objects that each include a `file_id` plus optional `attributes` or
          * `chunking_strategy`. Use this when you need to override metadata for specific files. The
          * global `attributes` or `chunking_strategy` will be ignored and must be specified for each
-         * file. The maximum batch size is 2000 files. Mutually exclusive with `file_ids`.
+         * file. The maximum batch size is 2000 files. This endpoint is recommended for multi-file
+         * ingestion and helps reduce per-vector-store write request pressure. Mutually exclusive
+         * with `file_ids`.
          */
         fun files(files: List<File>) = apply { body.files(files) }
 
@@ -465,7 +472,9 @@ private constructor(
          * A list of [File](https://platform.openai.com/docs/api-reference/files) IDs that the
          * vector store should use. Useful for tools like `file_search` that can access files. If
          * `attributes` or `chunking_strategy` are provided, they will be applied to all files in
-         * the batch. The maximum batch size is 2000 files. Mutually exclusive with `files`.
+         * the batch. The maximum batch size is 2000 files. This endpoint is recommended for
+         * multi-file ingestion and helps reduce per-vector-store write request pressure. Mutually
+         * exclusive with `files`.
          *
          * @throws OpenAIInvalidDataException if the JSON field has an unexpected type (e.g. if the
          *   server responded with an unexpected value).
@@ -476,7 +485,9 @@ private constructor(
          * A list of objects that each include a `file_id` plus optional `attributes` or
          * `chunking_strategy`. Use this when you need to override metadata for specific files. The
          * global `attributes` or `chunking_strategy` will be ignored and must be specified for each
-         * file. The maximum batch size is 2000 files. Mutually exclusive with `file_ids`.
+         * file. The maximum batch size is 2000 files. This endpoint is recommended for multi-file
+         * ingestion and helps reduce per-vector-store write request pressure. Mutually exclusive
+         * with `file_ids`.
          *
          * @throws OpenAIInvalidDataException if the JSON field has an unexpected type (e.g. if the
          *   server responded with an unexpected value).
@@ -623,8 +634,9 @@ private constructor(
              * A list of [File](https://platform.openai.com/docs/api-reference/files) IDs that the
              * vector store should use. Useful for tools like `file_search` that can access files.
              * If `attributes` or `chunking_strategy` are provided, they will be applied to all
-             * files in the batch. The maximum batch size is 2000 files. Mutually exclusive with
-             * `files`.
+             * files in the batch. The maximum batch size is 2000 files. This endpoint is
+             * recommended for multi-file ingestion and helps reduce per-vector-store write request
+             * pressure. Mutually exclusive with `files`.
              */
             fun fileIds(fileIds: List<String>) = fileIds(JsonField.of(fileIds))
 
@@ -655,8 +667,9 @@ private constructor(
              * A list of objects that each include a `file_id` plus optional `attributes` or
              * `chunking_strategy`. Use this when you need to override metadata for specific files.
              * The global `attributes` or `chunking_strategy` will be ignored and must be specified
-             * for each file. The maximum batch size is 2000 files. Mutually exclusive with
-             * `file_ids`.
+             * for each file. The maximum batch size is 2000 files. This endpoint is recommended for
+             * multi-file ingestion and helps reduce per-vector-store write request pressure.
+             * Mutually exclusive with `file_ids`.
              */
             fun files(files: List<File>) = files(JsonField.of(files))
 
@@ -902,7 +915,10 @@ private constructor(
 
         /**
          * A [File](https://platform.openai.com/docs/api-reference/files) ID that the vector store
-         * should use. Useful for tools like `file_search` that can access files.
+         * should use. Useful for tools like `file_search` that can access files. For multi-file
+         * ingestion, we recommend
+         * [`file_batches`](https://platform.openai.com/docs/api-reference/vector-stores-file-batches/createBatch)
+         * to minimize per-vector-store write requests.
          *
          * @throws OpenAIInvalidDataException if the JSON field has an unexpected type or is
          *   unexpectedly missing or null (e.g. if the server responded with an unexpected value).
@@ -1000,7 +1016,10 @@ private constructor(
 
             /**
              * A [File](https://platform.openai.com/docs/api-reference/files) ID that the vector
-             * store should use. Useful for tools like `file_search` that can access files.
+             * store should use. Useful for tools like `file_search` that can access files. For
+             * multi-file ingestion, we recommend
+             * [`file_batches`](https://platform.openai.com/docs/api-reference/vector-stores-file-batches/createBatch)
+             * to minimize per-vector-store write requests.
              */
             fun fileId(fileId: String) = fileId(JsonField.of(fileId))
 
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/vectorstores/files/FileCreateParams.kt b/openai-java-core/src/main/kotlin/com/openai/models/vectorstores/files/FileCreateParams.kt
@@ -42,7 +42,10 @@ private constructor(
 
     /**
      * A [File](https://platform.openai.com/docs/api-reference/files) ID that the vector store
-     * should use. Useful for tools like `file_search` that can access files.
+     * should use. Useful for tools like `file_search` that can access files. For multi-file
+     * ingestion, we recommend
+     * [`file_batches`](https://platform.openai.com/docs/api-reference/vector-stores-file-batches/createBatch)
+     * to minimize per-vector-store write requests.
      *
      * @throws OpenAIInvalidDataException if the JSON field has an unexpected type or is
      *   unexpectedly missing or null (e.g. if the server responded with an unexpected value).
@@ -149,7 +152,10 @@ private constructor(
 
         /**
          * A [File](https://platform.openai.com/docs/api-reference/files) ID that the vector store
-         * should use. Useful for tools like `file_search` that can access files.
+         * should use. Useful for tools like `file_search` that can access files. For multi-file
+         * ingestion, we recommend
+         * [`file_batches`](https://platform.openai.com/docs/api-reference/vector-stores-file-batches/createBatch)
+         * to minimize per-vector-store write requests.
          */
         fun fileId(fileId: String) = apply { body.fileId(fileId) }
 
@@ -397,7 +403,10 @@ private constructor(
 
         /**
          * A [File](https://platform.openai.com/docs/api-reference/files) ID that the vector store
-         * should use. Useful for tools like `file_search` that can access files.
+         * should use. Useful for tools like `file_search` that can access files. For multi-file
+         * ingestion, we recommend
+         * [`file_batches`](https://platform.openai.com/docs/api-reference/vector-stores-file-batches/createBatch)
+         * to minimize per-vector-store write requests.
          *
          * @throws OpenAIInvalidDataException if the JSON field has an unexpected type or is
          *   unexpectedly missing or null (e.g. if the server responded with an unexpected value).
@@ -495,7 +504,10 @@ private constructor(
 
             /**
              * A [File](https://platform.openai.com/docs/api-reference/files) ID that the vector
-             * store should use. Useful for tools like `file_search` that can access files.
+             * store should use. Useful for tools like `file_search` that can access files. For
+             * multi-file ingestion, we recommend
+             * [`file_batches`](https://platform.openai.com/docs/api-reference/vector-stores-file-batches/createBatch)
+             * to minimize per-vector-store write requests.
              */
             fun fileId(fileId: String) = fileId(JsonField.of(fileId))
 
