chore(api): docs and spec refactoring

stainless-app[bot] · stainless-app[bot] · commit a3f76bddd99c · 2025-09-15T20:10:03.000Z
diff --git a/.stats.yml b/.stats.yml
@@ -1,4 +1,4 @@
 configured_endpoints: 118
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-94b1e3cb0bdc616ff0c2f267c33dadd95f133b1f64e647aab6c64afb292b2793.yml
-openapi_spec_hash: 2395319ac9befd59b6536ae7f9564a05
-config_hash: 930dac3aa861344867e4ac84f037b5df
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-d30ff992a48873c1466c49f3c01f2ec8933faebff23424748f8d056065b1bcef.yml
+openapi_spec_hash: e933ec43b46f45c348adb78840e5808d
+config_hash: bf45940f0a7805b4ec2017eecdd36893
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/beta/assistants/AssistantCreateParams.kt b/openai-java-core/src/main/kotlin/com/openai/models/beta/assistants/AssistantCreateParams.kt
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/beta/threads/ThreadCreateAndRunParams.kt b/openai-java-core/src/main/kotlin/com/openai/models/beta/threads/ThreadCreateAndRunParams.kt
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/beta/threads/ThreadCreateParams.kt b/openai-java-core/src/main/kotlin/com/openai/models/beta/threads/ThreadCreateParams.kt
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/chat/completions/ChatCompletionListParams.kt b/openai-java-core/src/main/kotlin/com/openai/models/chat/completions/ChatCompletionListParams.kt
@@ -35,9 +35,12 @@ private constructor(
     fun limit(): Optional<Long> = Optional.ofNullable(limit)
 
     /**
-     * A list of metadata keys to filter the Chat Completions by. Example:
+     * Set of 16 key-value pairs that can be attached to an object. This can be useful for storing
+     * additional information about the object in a structured format, and querying for objects via
+     * API or the dashboard.
      *
-     * `metadata[key1]=value1&metadata[key2]=value2`
+     * Keys are strings with a maximum length of 64 characters. Values are strings with a maximum
+     * length of 512 characters.
      */
     fun metadata(): Optional<Metadata> = Optional.ofNullable(metadata)
 
@@ -108,9 +111,12 @@ private constructor(
         fun limit(limit: Optional<Long>) = limit(limit.getOrNull())
 
         /**
-         * A list of metadata keys to filter the Chat Completions by. Example:
+         * Set of 16 key-value pairs that can be attached to an object. This can be useful for
+         * storing additional information about the object in a structured format, and querying for
+         * objects via API or the dashboard.
          *
-         * `metadata[key1]=value1&metadata[key2]=value2`
+         * Keys are strings with a maximum length of 64 characters. Values are strings with a
+         * maximum length of 512 characters.
          */
         fun metadata(metadata: Metadata?) = apply { this.metadata = metadata }
 
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/conversations/ConversationCreateParams.kt b/openai-java-core/src/main/kotlin/com/openai/models/conversations/ConversationCreateParams.kt
@@ -49,8 +49,12 @@ private constructor(
     fun items(): Optional<List<ResponseInputItem>> = body.items()
 
     /**
-     * Set of 16 key-value pairs that can be attached to an object. Useful for storing additional
-     * information about the object in a structured format.
+     * Set of 16 key-value pairs that can be attached to an object. This can be useful for storing
+     * additional information about the object in a structured format, and querying for objects via
+     * API or the dashboard.
+     *
+     * Keys are strings with a maximum length of 64 characters. Values are strings with a maximum
+     * length of 512 characters.
      *
      * @throws OpenAIInvalidDataException if the JSON field has an unexpected type (e.g. if the
      *   server responded with an unexpected value).
@@ -277,8 +281,12 @@ private constructor(
         fun addItemReferenceItem(id: String) = apply { body.addItemReferenceItem(id) }
 
         /**
-         * Set of 16 key-value pairs that can be attached to an object. Useful for storing
-         * additional information about the object in a structured format.
+         * Set of 16 key-value pairs that can be attached to an object. This can be useful for
+         * storing additional information about the object in a structured format, and querying for
+         * objects via API or the dashboard.
+         *
+         * Keys are strings with a maximum length of 64 characters. Values are strings with a
+         * maximum length of 512 characters.
          */
         fun metadata(metadata: Metadata?) = apply { body.metadata(metadata) }
 
@@ -458,8 +466,12 @@ private constructor(
         fun items(): Optional<List<ResponseInputItem>> = items.getOptional("items")
 
         /**
-         * Set of 16 key-value pairs that can be attached to an object. Useful for storing
-         * additional information about the object in a structured format.
+         * Set of 16 key-value pairs that can be attached to an object. This can be useful for
+         * storing additional information about the object in a structured format, and querying for
+         * objects via API or the dashboard.
+         *
+         * Keys are strings with a maximum length of 64 characters. Values are strings with a
+         * maximum length of 512 characters.
          *
          * @throws OpenAIInvalidDataException if the JSON field has an unexpected type (e.g. if the
          *   server responded with an unexpected value).
@@ -697,8 +709,12 @@ private constructor(
                 )
 
             /**
-             * Set of 16 key-value pairs that can be attached to an object. Useful for storing
-             * additional information about the object in a structured format.
+             * Set of 16 key-value pairs that can be attached to an object. This can be useful for
+             * storing additional information about the object in a structured format, and querying
+             * for objects via API or the dashboard.
+             *
+             * Keys are strings with a maximum length of 64 characters. Values are strings with a
+             * maximum length of 512 characters.
              */
             fun metadata(metadata: Metadata?) = metadata(JsonField.ofNullable(metadata))
 
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/evals/runs/RunCancelResponse.kt b/openai-java-core/src/main/kotlin/com/openai/models/evals/runs/RunCancelResponse.kt
@@ -2725,8 +2725,11 @@ private constructor(
                     fun model(): Optional<String> = model.getOptional("model")
 
                     /**
-                     * Optional reasoning effort parameter. This is a query parameter used to select
-                     * responses.
+                     * Constrains effort on reasoning for
+                     * [reasoning models](https://platform.openai.com/docs/guides/reasoning).
+                     * Currently supported values are `minimal`, `low`, `medium`, and `high`.
+                     * Reducing reasoning effort can result in faster responses and fewer tokens
+                     * used on reasoning in a response.
                      *
                      * @throws OpenAIInvalidDataException if the JSON field has an unexpected type
                      *   (e.g. if the server responded with an unexpected value).
@@ -3037,8 +3040,11 @@ private constructor(
                         fun model(model: JsonField<String>) = apply { this.model = model }
 
                         /**
-                         * Optional reasoning effort parameter. This is a query parameter used to
-                         * select responses.
+                         * Constrains effort on reasoning for
+                         * [reasoning models](https://platform.openai.com/docs/guides/reasoning).
+                         * Currently supported values are `minimal`, `low`, `medium`, and `high`.
+                         * Reducing reasoning effort can result in faster responses and fewer tokens
+                         * used on reasoning in a response.
                          */
                         fun reasoningEffort(reasoningEffort: ReasoningEffort?) =
                             reasoningEffort(JsonField.ofNullable(reasoningEffort))
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/evals/runs/RunCreateParams.kt b/openai-java-core/src/main/kotlin/com/openai/models/evals/runs/RunCreateParams.kt
@@ -2487,8 +2487,11 @@ private constructor(
                     fun model(): Optional<String> = model.getOptional("model")
 
                     /**
-                     * Optional reasoning effort parameter. This is a query parameter used to select
-                     * responses.
+                     * Constrains effort on reasoning for
+                     * [reasoning models](https://platform.openai.com/docs/guides/reasoning).
+                     * Currently supported values are `minimal`, `low`, `medium`, and `high`.
+                     * Reducing reasoning effort can result in faster responses and fewer tokens
+                     * used on reasoning in a response.
                      *
                      * @throws OpenAIInvalidDataException if the JSON field has an unexpected type
                      *   (e.g. if the server responded with an unexpected value).
@@ -2797,8 +2800,11 @@ private constructor(
                         fun model(model: JsonField<String>) = apply { this.model = model }
 
                         /**
-                         * Optional reasoning effort parameter. This is a query parameter used to
-                         * select responses.
+                         * Constrains effort on reasoning for
+                         * [reasoning models](https://platform.openai.com/docs/guides/reasoning).
+                         * Currently supported values are `minimal`, `low`, `medium`, and `high`.
+                         * Reducing reasoning effort can result in faster responses and fewer tokens
+                         * used on reasoning in a response.
                          */
                         fun reasoningEffort(reasoningEffort: ReasoningEffort?) =
                             reasoningEffort(JsonField.ofNullable(reasoningEffort))
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/evals/runs/RunCreateResponse.kt b/openai-java-core/src/main/kotlin/com/openai/models/evals/runs/RunCreateResponse.kt
@@ -2725,8 +2725,11 @@ private constructor(
                     fun model(): Optional<String> = model.getOptional("model")
 
                     /**
-                     * Optional reasoning effort parameter. This is a query parameter used to select
-                     * responses.
+                     * Constrains effort on reasoning for
+                     * [reasoning models](https://platform.openai.com/docs/guides/reasoning).
+                     * Currently supported values are `minimal`, `low`, `medium`, and `high`.
+                     * Reducing reasoning effort can result in faster responses and fewer tokens
+                     * used on reasoning in a response.
                      *
                      * @throws OpenAIInvalidDataException if the JSON field has an unexpected type
                      *   (e.g. if the server responded with an unexpected value).
@@ -3037,8 +3040,11 @@ private constructor(
                         fun model(model: JsonField<String>) = apply { this.model = model }
 
                         /**
-                         * Optional reasoning effort parameter. This is a query parameter used to
-                         * select responses.
+                         * Constrains effort on reasoning for
+                         * [reasoning models](https://platform.openai.com/docs/guides/reasoning).
+                         * Currently supported values are `minimal`, `low`, `medium`, and `high`.
+                         * Reducing reasoning effort can result in faster responses and fewer tokens
+                         * used on reasoning in a response.
                          */
                         fun reasoningEffort(reasoningEffort: ReasoningEffort?) =
                             reasoningEffort(JsonField.ofNullable(reasoningEffort))
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/evals/runs/RunListResponse.kt b/openai-java-core/src/main/kotlin/com/openai/models/evals/runs/RunListResponse.kt
@@ -2725,8 +2725,11 @@ private constructor(
                     fun model(): Optional<String> = model.getOptional("model")
 
                     /**
-                     * Optional reasoning effort parameter. This is a query parameter used to select
-                     * responses.
+                     * Constrains effort on reasoning for
+                     * [reasoning models](https://platform.openai.com/docs/guides/reasoning).
+                     * Currently supported values are `minimal`, `low`, `medium`, and `high`.
+                     * Reducing reasoning effort can result in faster responses and fewer tokens
+                     * used on reasoning in a response.
                      *
                      * @throws OpenAIInvalidDataException if the JSON field has an unexpected type
                      *   (e.g. if the server responded with an unexpected value).
@@ -3037,8 +3040,11 @@ private constructor(
                         fun model(model: JsonField<String>) = apply { this.model = model }
 
                         /**
-                         * Optional reasoning effort parameter. This is a query parameter used to
-                         * select responses.
+                         * Constrains effort on reasoning for
+                         * [reasoning models](https://platform.openai.com/docs/guides/reasoning).
+                         * Currently supported values are `minimal`, `low`, `medium`, and `high`.
+                         * Reducing reasoning effort can result in faster responses and fewer tokens
+                         * used on reasoning in a response.
                          */
                         fun reasoningEffort(reasoningEffort: ReasoningEffort?) =
                             reasoningEffort(JsonField.ofNullable(reasoningEffort))
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/evals/runs/RunRetrieveResponse.kt b/openai-java-core/src/main/kotlin/com/openai/models/evals/runs/RunRetrieveResponse.kt
@@ -2725,8 +2725,11 @@ private constructor(
                     fun model(): Optional<String> = model.getOptional("model")
 
                     /**
-                     * Optional reasoning effort parameter. This is a query parameter used to select
-                     * responses.
+                     * Constrains effort on reasoning for
+                     * [reasoning models](https://platform.openai.com/docs/guides/reasoning).
+                     * Currently supported values are `minimal`, `low`, `medium`, and `high`.
+                     * Reducing reasoning effort can result in faster responses and fewer tokens
+                     * used on reasoning in a response.
                      *
                      * @throws OpenAIInvalidDataException if the JSON field has an unexpected type
                      *   (e.g. if the server responded with an unexpected value).
@@ -3037,8 +3040,11 @@ private constructor(
                         fun model(model: JsonField<String>) = apply { this.model = model }
 
                         /**
-                         * Optional reasoning effort parameter. This is a query parameter used to
-                         * select responses.
+                         * Constrains effort on reasoning for
+                         * [reasoning models](https://platform.openai.com/docs/guides/reasoning).
+                         * Currently supported values are `minimal`, `low`, `medium`, and `high`.
+                         * Reducing reasoning effort can result in faster responses and fewer tokens
+                         * used on reasoning in a response.
                          */
                         fun reasoningEffort(reasoningEffort: ReasoningEffort?) =
                             reasoningEffort(JsonField.ofNullable(reasoningEffort))
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/finetuning/jobs/FineTuningJob.kt b/openai-java-core/src/main/kotlin/com/openai/models/finetuning/jobs/FineTuningJob.kt
@@ -1411,8 +1411,8 @@ private constructor(
             /** Alias for calling [batchSize] with `BatchSize.ofAuto()`. */
             fun batchSizeAuto() = batchSize(BatchSize.ofAuto())
 
-            /** Alias for calling [batchSize] with `BatchSize.ofManual(manual)`. */
-            fun batchSize(manual: Long) = batchSize(BatchSize.ofManual(manual))
+            /** Alias for calling [batchSize] with `BatchSize.ofInteger(integer)`. */
+            fun batchSize(integer: Long) = batchSize(BatchSize.ofInteger(integer))
 
             /**
              * Scaling factor for the learning rate. A smaller learning rate may be useful to avoid
@@ -1542,28 +1542,28 @@ private constructor(
         class BatchSize
         private constructor(
             private val auto: JsonValue? = null,
-            private val manual: Long? = null,
+            private val integer: Long? = null,
             private val _json: JsonValue? = null,
         ) {
 
             fun auto(): Optional<JsonValue> = Optional.ofNullable(auto)
 
-            fun manual(): Optional<Long> = Optional.ofNullable(manual)
+            fun integer(): Optional<Long> = Optional.ofNullable(integer)
 
             fun isAuto(): Boolean = auto != null
 
-            fun isManual(): Boolean = manual != null
+            fun isInteger(): Boolean = integer != null
 
             fun asAuto(): JsonValue = auto.getOrThrow("auto")
 
-            fun asManual(): Long = manual.getOrThrow("manual")
+            fun asInteger(): Long = integer.getOrThrow("integer")
 
             fun _json(): Optional<JsonValue> = Optional.ofNullable(_json)
 
             fun <T> accept(visitor: Visitor<T>): T =
                 when {
                     auto != null -> visitor.visitAuto(auto)
-                    manual != null -> visitor.visitManual(manual)
+                    integer != null -> visitor.visitInteger(integer)
                     else -> visitor.unknown(_json)
                 }
 
@@ -1586,7 +1586,7 @@ private constructor(
                             }
                         }
 
-                        override fun visitManual(manual: Long) {}
+                        override fun visitInteger(integer: Long) {}
                     }
                 )
                 validated = true
@@ -1613,7 +1613,7 @@ private constructor(
                         override fun visitAuto(auto: JsonValue) =
                             auto.let { if (it == JsonValue.from("auto")) 1 else 0 }
 
-                        override fun visitManual(manual: Long) = 1
+                        override fun visitInteger(integer: Long) = 1
 
                         override fun unknown(json: JsonValue?) = 0
                     }
@@ -1624,15 +1624,15 @@ private constructor(
                     return true
                 }
 
-                return other is BatchSize && auto == other.auto && manual == other.manual
+                return other is BatchSize && auto == other.auto && integer == other.integer
             }
 
-            override fun hashCode(): Int = Objects.hash(auto, manual)
+            override fun hashCode(): Int = Objects.hash(auto, integer)
 
             override fun toString(): String =
                 when {
                     auto != null -> "BatchSize{auto=$auto}"
-                    manual != null -> "BatchSize{manual=$manual}"
+                    integer != null -> "BatchSize{integer=$integer}"
                     _json != null -> "BatchSize{_unknown=$_json}"
                     else -> throw IllegalStateException("Invalid BatchSize")
                 }
@@ -1641,7 +1641,7 @@ private constructor(
 
                 @JvmStatic fun ofAuto() = BatchSize(auto = JsonValue.from("auto"))
 
-                @JvmStatic fun ofManual(manual: Long) = BatchSize(manual = manual)
+                @JvmStatic fun ofInteger(integer: Long) = BatchSize(integer = integer)
             }
 
             /**
@@ -1652,7 +1652,7 @@ private constructor(
 
                 fun visitAuto(auto: JsonValue): T
 
-                fun visitManual(manual: Long): T
+                fun visitInteger(integer: Long): T
 
                 /**
                  * Maps an unknown variant of [BatchSize] to a value of type [T].
@@ -1680,7 +1680,7 @@ private constructor(
                                     ?.let { BatchSize(auto = it, _json = json) }
                                     ?.takeIf { it.isValid() },
                                 tryDeserialize(node, jacksonTypeRef<Long>())?.let {
-                                    BatchSize(manual = it, _json = json)
+                                    BatchSize(integer = it, _json = json)
                                 },
                             )
                             .filterNotNull()
@@ -1708,7 +1708,7 @@ private constructor(
                 ) {
                     when {
                         value.auto != null -> generator.writeObject(value.auto)
-                        value.manual != null -> generator.writeObject(value.manual)
+                        value.integer != null -> generator.writeObject(value.integer)
                         value._json != null -> generator.writeObject(value._json)
                         else -> throw IllegalStateException("Invalid BatchSize")
                     }
