release: 4.40.0

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "4.39.1"
+  ".": "4.40.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 261
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai/openai-0161cb2a0faadedfc17ff59c7fcad9671962dbd170f83811003c23702148cf36.yml
-openapi_spec_hash: 1023c7442d0e2e7e213e8b3a253921c5
-config_hash: e02ca1082421dfe55b145c45e95d6126
+configured_endpoints: 263
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai/openai-4db8edc05bd5503d4aaad74e8b9c783aa1f4d40382a8075c53355bd18dfaf68c.yml
+openapi_spec_hash: 2466f6ad496b27334217999202e185c0
+config_hash: ef3ce17315a31703e7af0567b3e9738c

CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 4.40.0 (2026-06-16)
+
+Full Changelog: [v4.39.1...v4.40.0](https://github.com/openai/openai-java/compare/v4.39.1...v4.40.0)
+
+### Features
+
+* **api:** admin spend_alerts ([512770c](https://github.com/openai/openai-java/commit/512770c119201347bfab9e68fec00e1cff5b2df8))
+* **api:** manual updates ([701ebe0](https://github.com/openai/openai-java/commit/701ebe011fa2ed05f80e51307bc7e9886bfb9d8b))
+* **api:** update OpenAPI spec or Stainless config ([94b7412](https://github.com/openai/openai-java/commit/94b7412a98fb60d6865d362c48526b4a6dd0896a))
+
+
+### Build System
+
+* Use CI environment for OpenAI API key workflow ([#756](https://github.com/openai/openai-java/issues/756)) ([27de5f5](https://github.com/openai/openai-java/commit/27de5f5b159394b7f29a31389854890460122c1a))
+* Use publish environment for release job ([#758](https://github.com/openai/openai-java/issues/758)) ([bbb66f8](https://github.com/openai/openai-java/commit/bbb66f870877a3e9e3f73c5c41eb4558f23a901a))
+
 ## 4.39.1 (2026-06-04)
 
 Full Changelog: [v4.39.0...v4.39.1](https://github.com/openai/openai-java/compare/v4.39.0...v4.39.1)

README.md

@@ -2,16 +2,16 @@
 
 <!-- x-release-please-start-version -->
 
-[![Maven Central](https://img.shields.io/maven-central/v/com.openai/openai-java)](https://central.sonatype.com/artifact/com.openai/openai-java/4.39.1)
-[![javadoc](https://javadoc.io/badge2/com.openai/openai-java/4.39.1/javadoc.svg)](https://javadoc.io/doc/com.openai/openai-java/4.39.1)
+[![Maven Central](https://img.shields.io/maven-central/v/com.openai/openai-java)](https://central.sonatype.com/artifact/com.openai/openai-java/4.40.0)
+[![javadoc](https://javadoc.io/badge2/com.openai/openai-java/4.40.0/javadoc.svg)](https://javadoc.io/doc/com.openai/openai-java/4.40.0)
 
 <!-- x-release-please-end -->
 
 The OpenAI Java SDK provides convenient access to the [OpenAI REST API](https://platform.openai.com/docs) from applications written in Java.
 
 <!-- x-release-please-start-version -->
 
-The REST API documentation can be found on [platform.openai.com](https://platform.openai.com/docs). Javadocs are available on [javadoc.io](https://javadoc.io/doc/com.openai/openai-java/4.39.1).
+The REST API documentation can be found on [platform.openai.com](https://platform.openai.com/docs). Javadocs are available on [javadoc.io](https://javadoc.io/doc/com.openai/openai-java/4.40.0).
 
 <!-- x-release-please-end -->
 
@@ -24,7 +24,7 @@ The REST API documentation can be found on [platform.openai.com](https://platfor
 ### Gradle
 
 ```kotlin
-implementation("com.openai:openai-java:4.39.1")
+implementation("com.openai:openai-java:4.40.0")
 ```
 
 ### Maven
@@ -33,7 +33,7 @@ implementation("com.openai:openai-java:4.39.1")
 <dependency>
   <groupId>com.openai</groupId>
   <artifactId>openai-java</artifactId>
-  <version>4.39.1</version>
+  <version>4.40.0</version>
 </dependency>
 ```
 
@@ -1433,7 +1433,7 @@ If you're using Spring Boot, then you can use the SDK's [Spring Boot starter](ht
 #### Gradle
 
 ```kotlin
-implementation("com.openai:openai-java-spring-boot-starter:4.39.1")
+implementation("com.openai:openai-java-spring-boot-starter:4.40.0")
 ```
 
 #### Maven
@@ -1442,7 +1442,7 @@ implementation("com.openai:openai-java-spring-boot-starter:4.39.1")
 <dependency>
   <groupId>com.openai</groupId>
   <artifactId>openai-java-spring-boot-starter</artifactId>
-  <version>4.39.1</version>
+  <version>4.40.0</version>
 </dependency>
 ```
 

build.gradle.kts

@@ -8,7 +8,7 @@ repositories {
 
 allprojects {
     group = "com.openai"
-    version = "4.39.1" // x-release-please-version
+    version = "4.40.0" // x-release-please-version
 }
 
 subprojects {

openai-java-core/src/main/kotlin/com/openai/models/Reasoning.kt

@@ -25,6 +25,7 @@ import kotlin.jvm.optionals.getOrNull
 class Reasoning
 @JsonCreator(mode = JsonCreator.Mode.DISABLED)
 private constructor(
+    private val context: JsonField<Context>,
     private val effort: JsonField<ReasoningEffort>,
     private val generateSummary: JsonField<GenerateSummary>,
     private val summary: JsonField<Summary>,
@@ -33,14 +34,24 @@ private constructor(
 
     @JsonCreator
     private constructor(
+        @JsonProperty("context") @ExcludeMissing context: JsonField<Context> = JsonMissing.of(),
         @JsonProperty("effort")
         @ExcludeMissing
         effort: JsonField<ReasoningEffort> = JsonMissing.of(),
         @JsonProperty("generate_summary")
         @ExcludeMissing
         generateSummary: JsonField<GenerateSummary> = JsonMissing.of(),
         @JsonProperty("summary") @ExcludeMissing summary: JsonField<Summary> = JsonMissing.of(),
-    ) : this(effort, generateSummary, summary, mutableMapOf())
+    ) : this(context, effort, generateSummary, summary, mutableMapOf())
+
+    /**
+     * Controls which reasoning items are rendered back to the model on later turns. When returned
+     * on a response, this is the effective reasoning context mode used for the response.
+     *
+     * @throws OpenAIInvalidDataException if the JSON field has an unexpected type (e.g. if the
+     *   server responded with an unexpected value).
+     */
+    fun context(): Optional<Context> = context.getOptional("context")
 
     /**
      * Constrains effort on reasoning for
@@ -85,6 +96,13 @@ private constructor(
      */
     fun summary(): Optional<Summary> = summary.getOptional("summary")
 
+    /**
+     * Returns the raw JSON value of [context].
+     *
+     * Unlike [context], this method doesn't throw if the JSON field has an unexpected type.
+     */
+    @JsonProperty("context") @ExcludeMissing fun _context(): JsonField<Context> = context
+
     /**
      * Returns the raw JSON value of [effort].
      *
@@ -130,19 +148,39 @@ private constructor(
     /** A builder for [Reasoning]. */
     class Builder internal constructor() {
 
+        private var context: JsonField<Context> = JsonMissing.of()
         private var effort: JsonField<ReasoningEffort> = JsonMissing.of()
         private var generateSummary: JsonField<GenerateSummary> = JsonMissing.of()
         private var summary: JsonField<Summary> = JsonMissing.of()
         private var additionalProperties: MutableMap<String, JsonValue> = mutableMapOf()
 
         @JvmSynthetic
         internal fun from(reasoning: Reasoning) = apply {
+            context = reasoning.context
             effort = reasoning.effort
             generateSummary = reasoning.generateSummary
             summary = reasoning.summary
             additionalProperties = reasoning.additionalProperties.toMutableMap()
         }
 
+        /**
+         * Controls which reasoning items are rendered back to the model on later turns. When
+         * returned on a response, this is the effective reasoning context mode used for the
+         * response.
+         */
+        fun context(context: Context?) = context(JsonField.ofNullable(context))
+
+        /** Alias for calling [Builder.context] with `context.orElse(null)`. */
+        fun context(context: Optional<Context>) = context(context.getOrNull())
+
+        /**
+         * Sets [Builder.context] to an arbitrary JSON value.
+         *
+         * You should usually call [Builder.context] with a well-typed [Context] value instead. This
+         * method is primarily for setting the field to an undocumented or not yet supported value.
+         */
+        fun context(context: JsonField<Context>) = apply { this.context = context }
+
         /**
          * Constrains effort on reasoning for
          * [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently
@@ -243,7 +281,13 @@ private constructor(
          * Further updates to this [Builder] will not mutate the returned instance.
          */
         fun build(): Reasoning =
-            Reasoning(effort, generateSummary, summary, additionalProperties.toMutableMap())
+            Reasoning(
+                context,
+                effort,
+                generateSummary,
+                summary,
+                additionalProperties.toMutableMap(),
+            )
     }
 
     private var validated: Boolean = false
@@ -261,6 +305,7 @@ private constructor(
             return@apply
         }
 
+        context().ifPresent { it.validate() }
         effort().ifPresent { it.validate() }
         generateSummary().ifPresent { it.validate() }
         summary().ifPresent { it.validate() }
@@ -282,10 +327,155 @@ private constructor(
      */
     @JvmSynthetic
     internal fun validity(): Int =
-        (effort.asKnown().getOrNull()?.validity() ?: 0) +
+        (context.asKnown().getOrNull()?.validity() ?: 0) +
+            (effort.asKnown().getOrNull()?.validity() ?: 0) +
             (generateSummary.asKnown().getOrNull()?.validity() ?: 0) +
             (summary.asKnown().getOrNull()?.validity() ?: 0)
 
+    /**
+     * Controls which reasoning items are rendered back to the model on later turns. When returned
+     * on a response, this is the effective reasoning context mode used for the response.
+     */
+    class Context @JsonCreator private constructor(private val value: JsonField<String>) : Enum {
+
+        /**
+         * Returns this class instance's raw value.
+         *
+         * This is usually only useful if this instance was deserialized from data that doesn't
+         * match any known member, and you want to know that value. For example, if the SDK is on an
+         * older version than the API, then the API may respond with new members that the SDK is
+         * unaware of.
+         */
+        @com.fasterxml.jackson.annotation.JsonValue fun _value(): JsonField<String> = value
+
+        companion object {
+
+            @JvmField val AUTO = of("auto")
+
+            @JvmField val CURRENT_TURN = of("current_turn")
+
+            @JvmField val ALL_TURNS = of("all_turns")
+
+            @JvmStatic fun of(value: String) = Context(JsonField.of(value))
+        }
+
+        /** An enum containing [Context]'s known values. */
+        enum class Known {
+            AUTO,
+            CURRENT_TURN,
+            ALL_TURNS,
+        }
+
+        /**
+         * An enum containing [Context]'s known values, as well as an [_UNKNOWN] member.
+         *
+         * An instance of [Context] can contain an unknown value in a couple of cases:
+         * - It was deserialized from data that doesn't match any known member. For example, if the
+         *   SDK is on an older version than the API, then the API may respond with new members that
+         *   the SDK is unaware of.
+         * - It was constructed with an arbitrary value using the [of] method.
+         */
+        enum class Value {
+            AUTO,
+            CURRENT_TURN,
+            ALL_TURNS,
+            /** An enum member indicating that [Context] was instantiated with an unknown value. */
+            _UNKNOWN,
+        }
+
+        /**
+         * Returns an enum member corresponding to this class instance's value, or [Value._UNKNOWN]
+         * if the class was instantiated with an unknown value.
+         *
+         * Use the [known] method instead if you're certain the value is always known or if you want
+         * to throw for the unknown case.
+         */
+        fun value(): Value =
+            when (this) {
+                AUTO -> Value.AUTO
+                CURRENT_TURN -> Value.CURRENT_TURN
+                ALL_TURNS -> Value.ALL_TURNS
+                else -> Value._UNKNOWN
+            }
+
+        /**
+         * Returns an enum member corresponding to this class instance's value.
+         *
+         * Use the [value] method instead if you're uncertain the value is always known and don't
+         * want to throw for the unknown case.
+         *
+         * @throws OpenAIInvalidDataException if this class instance's value is a not a known
+         *   member.
+         */
+        fun known(): Known =
+            when (this) {
+                AUTO -> Known.AUTO
+                CURRENT_TURN -> Known.CURRENT_TURN
+                ALL_TURNS -> Known.ALL_TURNS
+                else -> throw OpenAIInvalidDataException("Unknown Context: $value")
+            }
+
+        /**
+         * Returns this class instance's primitive wire representation.
+         *
+         * This differs from the [toString] method because that method is primarily for debugging
+         * and generally doesn't throw.
+         *
+         * @throws OpenAIInvalidDataException if this class instance's value does not have the
+         *   expected primitive type.
+         */
+        fun asString(): String =
+            _value().asString().orElseThrow { OpenAIInvalidDataException("Value is not a String") }
+
+        private var validated: Boolean = false
+
+        /**
+         * Validates that the types of all values in this object match their expected types
+         * recursively.
+         *
+         * This method is _not_ forwards compatible with new types from the API for existing fields.
+         *
+         * @throws OpenAIInvalidDataException if any value type in this object doesn't match its
+         *   expected type.
+         */
+        fun validate(): Context = apply {
+            if (validated) {
+                return@apply
+            }
+
+            known()
+            validated = true
+        }
+
+        fun isValid(): Boolean =
+            try {
+                validate()
+                true
+            } catch (e: OpenAIInvalidDataException) {
+                false
+            }
+
+        /**
+         * Returns a score indicating how many valid values are contained in this object
+         * recursively.
+         *
+         * Used for best match union deserialization.
+         */
+        @JvmSynthetic internal fun validity(): Int = if (value() == Value._UNKNOWN) 0 else 1
+
+        override fun equals(other: Any?): Boolean {
+            if (this === other) {
+                return true
+            }
+
+            return other is Context && value == other.value
+        }
+
+        override fun hashCode() = value.hashCode()
+
+        override fun toString() = value.toString()
+    }
+
     /**
      * **Deprecated:** use `summary` instead.
      *
@@ -590,18 +780,19 @@ private constructor(
         }
 
         return other is Reasoning &&
+            context == other.context &&
             effort == other.effort &&
             generateSummary == other.generateSummary &&
             summary == other.summary &&
             additionalProperties == other.additionalProperties
     }
 
     private val hashCode: Int by lazy {
-        Objects.hash(effort, generateSummary, summary, additionalProperties)
+        Objects.hash(context, effort, generateSummary, summary, additionalProperties)
     }
 
     override fun hashCode(): Int = hashCode
 
     override fun toString() =
-        "Reasoning{effort=$effort, generateSummary=$generateSummary, summary=$summary, additionalProperties=$additionalProperties}"
+        "Reasoning{context=$context, effort=$effort, generateSummary=$generateSummary, summary=$summary, additionalProperties=$additionalProperties}"
 }