chore(api): clarify external storage deletion behavior (#1057)

## Summary

Clarifies how disconnecting an external storage configuration affects
project retention settings and cloud storage.

## Changes

- Document restoration of organization-default retention when the last
project configuration is removed.
- Explain that repeated deletion completes interrupted retention updates
and leaves cloud storage unchanged.

Co-authored-by: marcuswood-oai <323319819+marcuswood-oai@users.noreply.github.com>

Author: marcuswood-oai

.castiron.stats.yml

@@ -1,8 +1,8 @@
 schema_version: 1
-generation_id: c5d3dd34-f750-47f7-97dd-2b06d84974c7
-openapi_spec_hash: ce912f79d7f8cb19a7a515513c214b8a
-openapi_transformed_spec_hash: 352b5a7a028f990b6475b6593e381eee
-config_hash: dde98d9c41cd6f4163320f92c70f83e6
-codegen_sha: 2a14074079a9331f4b3e7638ded42c0a8dbe2541
-codegen_hash: b09f75ad1d66062668b44c17bd3ca8bd060baaf16c3b1a892eb8e49f2a0d97fe
-public_codegen_sha: a817eabe36bad4c6479430cbe9f29fe353499c10
+generation_id: df13bfb8-f64e-490b-8449-3b4b10b30510
+openapi_spec_hash: 3a0031a277862428a7586125d5cec8c8
+openapi_transformed_spec_hash: 951060c87157ffcd2b99d6ec617d2f6b
+config_hash: 18f602826c88bad76c6fdf08ab67247a
+codegen_sha: cd85f5100378285631495fa9381b12beeb3724a2
+codegen_hash: b053bfcf443accffd13c8738807d62816189e2c775d56d2bc17819715f9f3f85
+public_codegen_sha: 3b35198fa93c82ca0ce4f3431706f523a80fe6f5

api_reference/openapi.transformed.yml

@@ -22961,7 +22961,7 @@ paths:
       - AdminApiKeyAuth: []
     delete:
       summary: Delete an external storage configuration
-      description: Soft-delete one customer-managed external storage configuration.
+      description: Disconnect a customer-managed external storage configuration. Removing the project's last configuration restores organization-default retention if customer-managed retention was active. Repeating a deletion also completes any interrupted retention update. Cloud storage is unchanged.
       operationId: Deleteanexternalstorageconfiguration
       parameters:
       - name: external_storage_id
@@ -80509,6 +80509,7 @@ components:
           - $ref: '#/components/schemas/ReasoningEffortParam'
           - type: 'null'
           description: Omit to keep the current effort. Null selects the model's default effort.
+          x-openai-go-optional-enum: true
       additionalProperties: false
       description: Reasoning effort for subsequent turns. The reasoning summary stays unchanged.
     UpdateSessionAgentParam:
@@ -80527,6 +80528,7 @@ components:
           - $ref: '#/components/schemas/ServiceTierParam'
           - type: 'null'
           description: Omit to keep the current tier. Null resets it to auto.
+          x-openai-go-optional-enum: true
       additionalProperties: false
       description: Model settings that can change after session creation.
     UpdateAgentSessionParams:
@@ -96391,6 +96393,7 @@ components:
       - gpt-5.1
       - gpt-5.1-2025-11-13
       - gpt-5.1-codex
+      - gpt-5.1-mini
       - gpt-5.1-chat-latest
       - gpt-5
       - gpt-5-mini

openai-java-core/src/main/kotlin/com/openai/models/admin/organization/externalstorage/ExternalStorageDeleteParams.kt

@@ -11,7 +11,11 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/** Soft-delete one customer-managed external storage configuration. */
+/**
+ * Disconnect a customer-managed external storage configuration. Removing the project's last
+ * configuration restores organization-default retention if customer-managed retention was active.
+ * Repeating a deletion also completes any interrupted retention update. Cloud storage is unchanged.
+ */
 class ExternalStorageDeleteParams
 private constructor(
     private val externalStorageId: String?,

openai-java-core/src/main/kotlin/com/openai/services/async/SafetyServiceAsync.kt

@@ -21,10 +21,10 @@ interface SafetyServiceAsync {
      */
     fun withOptions(modifier: Consumer<ClientOptions.Builder>): SafetyServiceAsync
 
-    fun alerts(): AlertServiceAsync
-
     fun cases(): CaseServiceAsync
 
+    fun alerts(): AlertServiceAsync
+
     /**
      * A view of [SafetyServiceAsync] that provides access to raw HTTP responses for each method.
      */
@@ -39,8 +39,8 @@ interface SafetyServiceAsync {
             modifier: Consumer<ClientOptions.Builder>
         ): SafetyServiceAsync.WithRawResponse
 
-        fun alerts(): AlertServiceAsync.WithRawResponse
-
         fun cases(): CaseServiceAsync.WithRawResponse
+
+        fun alerts(): AlertServiceAsync.WithRawResponse
     }
 }

openai-java-core/src/main/kotlin/com/openai/services/async/SafetyServiceAsyncImpl.kt

@@ -16,39 +16,39 @@ class SafetyServiceAsyncImpl internal constructor(private val clientOptions: Cli
         WithRawResponseImpl(clientOptions)
     }
 
-    private val alerts: AlertServiceAsync by lazy { AlertServiceAsyncImpl(clientOptions) }
-
     private val cases: CaseServiceAsync by lazy { CaseServiceAsyncImpl(clientOptions) }
 
+    private val alerts: AlertServiceAsync by lazy { AlertServiceAsyncImpl(clientOptions) }
+
     override fun withRawResponse(): SafetyServiceAsync.WithRawResponse = withRawResponse
 
     override fun withOptions(modifier: Consumer<ClientOptions.Builder>): SafetyServiceAsync =
         SafetyServiceAsyncImpl(clientOptions.toBuilder().apply(modifier::accept).build())
 
-    override fun alerts(): AlertServiceAsync = alerts
-
     override fun cases(): CaseServiceAsync = cases
 
+    override fun alerts(): AlertServiceAsync = alerts
+
     class WithRawResponseImpl internal constructor(private val clientOptions: ClientOptions) :
         SafetyServiceAsync.WithRawResponse {
 
-        private val alerts: AlertServiceAsync.WithRawResponse by lazy {
-            AlertServiceAsyncImpl.WithRawResponseImpl(clientOptions)
-        }
-
         private val cases: CaseServiceAsync.WithRawResponse by lazy {
             CaseServiceAsyncImpl.WithRawResponseImpl(clientOptions)
         }
 
+        private val alerts: AlertServiceAsync.WithRawResponse by lazy {
+            AlertServiceAsyncImpl.WithRawResponseImpl(clientOptions)
+        }
+
         override fun withOptions(
             modifier: Consumer<ClientOptions.Builder>
         ): SafetyServiceAsync.WithRawResponse =
             SafetyServiceAsyncImpl.WithRawResponseImpl(
                 clientOptions.toBuilder().apply(modifier::accept).build()
             )
 
-        override fun alerts(): AlertServiceAsync.WithRawResponse = alerts
-
         override fun cases(): CaseServiceAsync.WithRawResponse = cases
+
+        override fun alerts(): AlertServiceAsync.WithRawResponse = alerts
     }
 }

openai-java-core/src/main/kotlin/com/openai/services/async/admin/OrganizationServiceAsync.kt

@@ -32,8 +32,6 @@ interface OrganizationServiceAsync {
      */
     fun withOptions(modifier: Consumer<ClientOptions.Builder>): OrganizationServiceAsync
 
-    fun externalStorage(): ExternalStorageServiceAsync
-
     /** List user actions and configuration changes within this organization. */
     fun auditLogs(): AuditLogServiceAsync
 
@@ -51,6 +49,8 @@ interface OrganizationServiceAsync {
 
     fun dataRetention(): DataRetentionServiceAsync
 
+    fun externalStorage(): ExternalStorageServiceAsync
+
     fun spendLimit(): SpendLimitServiceAsync
 
     fun spendAlerts(): SpendAlertServiceAsync
@@ -74,8 +74,6 @@ interface OrganizationServiceAsync {
             modifier: Consumer<ClientOptions.Builder>
         ): OrganizationServiceAsync.WithRawResponse
 
-        fun externalStorage(): ExternalStorageServiceAsync.WithRawResponse
-
         /** List user actions and configuration changes within this organization. */
         fun auditLogs(): AuditLogServiceAsync.WithRawResponse
 
@@ -93,6 +91,8 @@ interface OrganizationServiceAsync {
 
         fun dataRetention(): DataRetentionServiceAsync.WithRawResponse
 
+        fun externalStorage(): ExternalStorageServiceAsync.WithRawResponse
+
         fun spendLimit(): SpendLimitServiceAsync.WithRawResponse
 
         fun spendAlerts(): SpendAlertServiceAsync.WithRawResponse

openai-java-core/src/main/kotlin/com/openai/services/async/admin/OrganizationServiceAsyncImpl.kt

@@ -38,10 +38,6 @@ class OrganizationServiceAsyncImpl internal constructor(private val clientOption
         WithRawResponseImpl(clientOptions)
     }
 
-    private val externalStorage: ExternalStorageServiceAsync by lazy {
-        ExternalStorageServiceAsyncImpl(clientOptions)
-    }
-
     private val auditLogs: AuditLogServiceAsync by lazy { AuditLogServiceAsyncImpl(clientOptions) }
 
     private val adminApiKeys: AdminApiKeyServiceAsync by lazy {
@@ -62,6 +58,10 @@ class OrganizationServiceAsyncImpl internal constructor(private val clientOption
         DataRetentionServiceAsyncImpl(clientOptions)
     }
 
+    private val externalStorage: ExternalStorageServiceAsync by lazy {
+        ExternalStorageServiceAsyncImpl(clientOptions)
+    }
+
     private val spendLimit: SpendLimitServiceAsync by lazy {
         SpendLimitServiceAsyncImpl(clientOptions)
     }
@@ -81,8 +81,6 @@ class OrganizationServiceAsyncImpl internal constructor(private val clientOption
     override fun withOptions(modifier: Consumer<ClientOptions.Builder>): OrganizationServiceAsync =
         OrganizationServiceAsyncImpl(clientOptions.toBuilder().apply(modifier::accept).build())
 
-    override fun externalStorage(): ExternalStorageServiceAsync = externalStorage
-
     /** List user actions and configuration changes within this organization. */
     override fun auditLogs(): AuditLogServiceAsync = auditLogs
 
@@ -100,6 +98,8 @@ class OrganizationServiceAsyncImpl internal constructor(private val clientOption
 
     override fun dataRetention(): DataRetentionServiceAsync = dataRetention
 
+    override fun externalStorage(): ExternalStorageServiceAsync = externalStorage
+
     override fun spendLimit(): SpendLimitServiceAsync = spendLimit
 
     override fun spendAlerts(): SpendAlertServiceAsync = spendAlerts
@@ -111,10 +111,6 @@ class OrganizationServiceAsyncImpl internal constructor(private val clientOption
     class WithRawResponseImpl internal constructor(private val clientOptions: ClientOptions) :
         OrganizationServiceAsync.WithRawResponse {
 
-        private val externalStorage: ExternalStorageServiceAsync.WithRawResponse by lazy {
-            ExternalStorageServiceAsyncImpl.WithRawResponseImpl(clientOptions)
-        }
-
         private val auditLogs: AuditLogServiceAsync.WithRawResponse by lazy {
             AuditLogServiceAsyncImpl.WithRawResponseImpl(clientOptions)
         }
@@ -147,6 +143,10 @@ class OrganizationServiceAsyncImpl internal constructor(private val clientOption
             DataRetentionServiceAsyncImpl.WithRawResponseImpl(clientOptions)
         }
 
+        private val externalStorage: ExternalStorageServiceAsync.WithRawResponse by lazy {
+            ExternalStorageServiceAsyncImpl.WithRawResponseImpl(clientOptions)
+        }
+
         private val spendLimit: SpendLimitServiceAsync.WithRawResponse by lazy {
             SpendLimitServiceAsyncImpl.WithRawResponseImpl(clientOptions)
         }
@@ -170,9 +170,6 @@ class OrganizationServiceAsyncImpl internal constructor(private val clientOption
                 clientOptions.toBuilder().apply(modifier::accept).build()
             )
 
-        override fun externalStorage(): ExternalStorageServiceAsync.WithRawResponse =
-            externalStorage
-
         /** List user actions and configuration changes within this organization. */
         override fun auditLogs(): AuditLogServiceAsync.WithRawResponse = auditLogs
 
@@ -190,6 +187,9 @@ class OrganizationServiceAsyncImpl internal constructor(private val clientOption
 
         override fun dataRetention(): DataRetentionServiceAsync.WithRawResponse = dataRetention
 
+        override fun externalStorage(): ExternalStorageServiceAsync.WithRawResponse =
+            externalStorage
+
         override fun spendLimit(): SpendLimitServiceAsync.WithRawResponse = spendLimit
 
         override fun spendAlerts(): SpendAlertServiceAsync.WithRawResponse = spendAlerts

openai-java-core/src/main/kotlin/com/openai/services/async/admin/organization/ExternalStorageServiceAsync.kt

@@ -97,7 +97,12 @@ interface ExternalStorageServiceAsync {
     fun list(requestOptions: RequestOptions): CompletableFuture<ExternalStorageListPageAsync> =
         list(ExternalStorageListParams.none(), requestOptions)
 
-    /** Soft-delete one customer-managed external storage configuration. */
+    /**
+     * Disconnect a customer-managed external storage configuration. Removing the project's last
+     * configuration restores organization-default retention if customer-managed retention was
+     * active. Repeating a deletion also completes any interrupted retention update. Cloud storage
+     * is unchanged.
+     */
     fun delete(externalStorageId: String): CompletableFuture<ExternalStorageDeleted> =
         delete(externalStorageId, ExternalStorageDeleteParams.none())
 

openai-java-core/src/main/kotlin/com/openai/services/blocking/SafetyService.kt

@@ -21,10 +21,10 @@ interface SafetyService {
      */
     fun withOptions(modifier: Consumer<ClientOptions.Builder>): SafetyService
 
-    fun alerts(): AlertService
-
     fun cases(): CaseService
 
+    fun alerts(): AlertService
+
     /** A view of [SafetyService] that provides access to raw HTTP responses for each method. */
     interface WithRawResponse {
 
@@ -35,8 +35,8 @@ interface SafetyService {
          */
         fun withOptions(modifier: Consumer<ClientOptions.Builder>): SafetyService.WithRawResponse
 
-        fun alerts(): AlertService.WithRawResponse
-
         fun cases(): CaseService.WithRawResponse
+
+        fun alerts(): AlertService.WithRawResponse
     }
 }

openai-java-core/src/main/kotlin/com/openai/services/blocking/SafetyServiceImpl.kt

@@ -16,39 +16,39 @@ class SafetyServiceImpl internal constructor(private val clientOptions: ClientOp
         WithRawResponseImpl(clientOptions)
     }
 
-    private val alerts: AlertService by lazy { AlertServiceImpl(clientOptions) }
-
     private val cases: CaseService by lazy { CaseServiceImpl(clientOptions) }
 
+    private val alerts: AlertService by lazy { AlertServiceImpl(clientOptions) }
+
     override fun withRawResponse(): SafetyService.WithRawResponse = withRawResponse
 
     override fun withOptions(modifier: Consumer<ClientOptions.Builder>): SafetyService =
         SafetyServiceImpl(clientOptions.toBuilder().apply(modifier::accept).build())
 
-    override fun alerts(): AlertService = alerts
-
     override fun cases(): CaseService = cases
 
+    override fun alerts(): AlertService = alerts
+
     class WithRawResponseImpl internal constructor(private val clientOptions: ClientOptions) :
         SafetyService.WithRawResponse {
 
-        private val alerts: AlertService.WithRawResponse by lazy {
-            AlertServiceImpl.WithRawResponseImpl(clientOptions)
-        }
-
         private val cases: CaseService.WithRawResponse by lazy {
             CaseServiceImpl.WithRawResponseImpl(clientOptions)
         }
 
+        private val alerts: AlertService.WithRawResponse by lazy {
+            AlertServiceImpl.WithRawResponseImpl(clientOptions)
+        }
+
         override fun withOptions(
             modifier: Consumer<ClientOptions.Builder>
         ): SafetyService.WithRawResponse =
             SafetyServiceImpl.WithRawResponseImpl(
                 clientOptions.toBuilder().apply(modifier::accept).build()
             )
 
-        override fun alerts(): AlertService.WithRawResponse = alerts
-
         override fun cases(): CaseService.WithRawResponse = cases
+
+        override fun alerts(): AlertService.WithRawResponse = alerts
     }
 }