feat(api): add vault metadata and clarify web search locations

.castiron.stats.yml

@@ -1,8 +1,8 @@
 schema_version: 1
-generation_id: d9e3b632-5822-43f8-a0de-0cd04d09db33
-openapi_spec_hash: 687580b2f55d2dada661f0387a4b3e0d
-openapi_transformed_spec_hash: 904296217a5077aa14766c6c58aa87d9
+generation_id: 8201fc3a-01b9-4448-881a-235175bb31dc
+openapi_spec_hash: fab08c2fec3b3d48fe3dacb03a098e44
+openapi_transformed_spec_hash: 3aaecb059340443ef1b2d783439b1a10
 config_hash: 84cdcc959ee7140cc9a65e9b642c097b
-codegen_sha: 41ac0d43560df6c0983b529a6112e2c437ead2d1
-codegen_hash: 614193cc88f476d3dbfe7d149d8adf21489f235af4454fb1e93628fe43e1e351
-public_codegen_sha: 2722089d4e9342c45f1ddbda6e7b4b72511d961f
+codegen_sha: bf96e48cbc295253520266217a5d104556d06abc
+codegen_hash: 9b9fdfdef42eee49f4577fc0dfa1cde9a88c29e47cf9222ff99a356e5466a6a0
+public_codegen_sha: 83d8728da764f7328630ba3faae435bb5b7cd9c3

api_reference/openapi.transformed.yml

@@ -28461,8 +28461,8 @@ paths:
                 $ref: '#/components/schemas/ErrorResponse-2'
     post:
       operationId: rotateVaultCredential
-      summary: Rotate a vault credential
-      description: Rotates a vault credential's write-only secret and returns only credential metadata. See [vaults](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults).
+      summary: Update a vault credential
+      description: Updates credential metadata or rotates its write-only secret. See [vaults](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults).
       tags:
       - Vaults
       parameters:
@@ -28489,7 +28489,7 @@ paths:
               $ref: '#/components/schemas/RotateVaultCredentialParams'
       responses:
         '200':
-          description: The rotated vault credential without secret values.
+          description: The updated vault credential without secret values.
           content:
             application/json:
               schema:
@@ -35529,6 +35529,7 @@ components:
               propertyName: type
           seed:
             type: integer
+            format: int64
             minimum: -9223372036854775808
             maximum: 9223372036854775807
             nullable: true
@@ -35539,7 +35540,6 @@ components:
               Determinism is not guaranteed, and you should refer to the `system_fingerprint` response parameter to monitor changes in the backend.
             x-oaiMeta:
               beta: true
-            format: int64
           stream_options:
             $ref: '#/components/schemas/ChatCompletionStreamOptions'
           tools:
@@ -65416,6 +65416,10 @@ components:
           - type: 'null'
         user_location:
           $ref: '#/components/schemas/WebSearchApproximateLocation'
+          description: |
+            The approximate location of the user. If omitted or null, defaults to the
+            United States. To avoid this fallback, pass `{"type": "approximate"}` without
+            location fields. To localize results, provide the relevant location fields.
         search_context_size:
           type: string
           enum:
@@ -68571,7 +68575,7 @@ components:
         user_location:
           anyOf:
           - $ref: '#/components/schemas/ApproximateLocation'
-            description: The user's location.
+            description: 'The approximate location of the user. If omitted or null, defaults to the United States. To avoid this fallback, pass `{"type": "approximate"}` without location fields. To localize results, provide the relevant location fields.'
           - type: 'null'
         search_context_size:
           $ref: '#/components/schemas/SearchContextSize'
@@ -81281,6 +81285,16 @@ components:
         auth:
           $ref: '#/components/schemas/VaultCredentialAuthResource'
           description: The authentication method and non-secret configuration of the credential.
+        metadata:
+          type: object
+          additionalProperties:
+            type: string
+            minLength: 0
+          propertyNames:
+            type: string
+            minLength: 0
+          minProperties: 0
+          description: Application-defined key-value pairs associated with this credential.
         created_at:
           type: integer
           format: int64
@@ -81295,6 +81309,7 @@ components:
       - vault_id
       - name
       - auth
+      - metadata
       - created_at
       - updated_at
       additionalProperties: false
@@ -81623,6 +81638,19 @@ components:
         auth:
           $ref: '#/components/schemas/CreateVaultCredentialAuthParam'
           description: The authentication method and write-only secret values to store.
+        metadata:
+          type: object
+          additionalProperties:
+            type: string
+            minLength: 0
+            maxLength: 512
+          propertyNames:
+            type: string
+            minLength: 1
+            maxLength: 64
+          minProperties: 0
+          maxProperties: 16
+          description: Up to 16 string key-value pairs, with keys up to 64 and values up to 512 characters. Defaults to an empty map.
       required:
       - auth
       - name
@@ -81802,10 +81830,21 @@ components:
         auth:
           $ref: '#/components/schemas/RotateVaultCredentialAuthParam'
           description: Replacement values for the credential's existing authentication method.
-      required:
-      - auth
+        metadata:
+          type: object
+          additionalProperties:
+            type: string
+            minLength: 0
+            maxLength: 512
+          propertyNames:
+            type: string
+            minLength: 1
+            maxLength: 64
+          minProperties: 0
+          maxProperties: 16
+          description: Replaces all metadata. Omit to preserve it, or pass {} to clear it. Up to 16 string key-value pairs, with keys up to 64 and values up to 512 characters.
       additionalProperties: false
-      description: Secret, expiry, and OAuth refresh scope updates for an existing vault credential.
+      description: Metadata, secret, expiry, and OAuth refresh scope updates for an existing vault credential. Supply at least one of `auth` or `metadata`.
     DeletedVaultCredentialResource:
       type: object
       properties:
@@ -84506,7 +84545,7 @@ components:
         user_location:
           anyOf:
           - $ref: '#/components/schemas/BetaApproximateLocation'
-            description: The user's location.
+            description: 'The approximate location of the user. If omitted or null, defaults to the United States. To avoid this fallback, pass `{"type": "approximate"}` without location fields. To localize results, provide the relevant location fields.'
           - type: 'null'
         search_context_size:
           $ref: '#/components/schemas/BetaSearchContextSize'
@@ -85464,6 +85503,10 @@ components:
           - type: 'null'
         user_location:
           $ref: '#/components/schemas/BetaWebSearchApproximateLocation'
+          description: |
+            The approximate location of the user. If omitted or null, defaults to the
+            United States. To avoid this fallback, pass `{"type": "approximate"}` without
+            location fields. To localize results, provide the relevant location fields.
         search_context_size:
           type: string
           enum:

src/openai/resources/beta/agents/vaults/credentials.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Optional
+from typing import Dict, Optional
 from typing_extensions import Literal
 
 import httpx2
@@ -55,6 +55,7 @@ def create(
         *,
         auth: CredentialAuthCreateParam,
         name: str,
+        metadata: Dict[str, str] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
@@ -74,6 +75,9 @@ def create(
           name: The name is trimmed before storage. It must contain 1 to 256 UTF-8 bytes after
               trimming.
 
+          metadata: Up to 16 string key-value pairs, with keys up to 64 and values up to 512
+              characters. Defaults to an empty map.
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -91,6 +95,7 @@ def create(
                 {
                     "auth": auth,
                     "name": name,
+                    "metadata": metadata,
                 },
                 credential_create_params.CredentialCreateParams,
             ),
@@ -154,22 +159,26 @@ def update(
         credential_id: str,
         *,
         vault_id: str,
-        auth: CredentialAuthRotateParam,
+        auth: CredentialAuthRotateParam | Omit = omit,
+        metadata: Dict[str, str] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
         extra_query: Query | None = None,
         extra_body: Body | None = None,
         timeout: float | httpx2.Timeout | None | NotGiven = not_given,
     ) -> Credential:
-        """
-        Rotates a vault credential's write-only secret and returns only credential
-        metadata. See
+        """Updates credential metadata or rotates its write-only secret.
+
+        See
         [vaults](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults).
 
         Args:
           auth: Replacement values for the credential's existing authentication method.
 
+          metadata: Replaces all metadata. Omit to preserve it, or pass {} to clear it. Up to 16
+              string key-value pairs, with keys up to 64 and values up to 512 characters.
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -187,7 +196,13 @@ def update(
             path_template(
                 "/vaults/{vault_id}/credentials/{credential_id}", vault_id=vault_id, credential_id=credential_id
             ),
-            body=maybe_transform({"auth": auth}, credential_update_params.CredentialUpdateParams),
+            body=maybe_transform(
+                {
+                    "auth": auth,
+                    "metadata": metadata,
+                },
+                credential_update_params.CredentialUpdateParams,
+            ),
             options=make_request_options(
                 extra_headers=extra_headers,
                 extra_query=extra_query,
@@ -338,6 +353,7 @@ async def create(
         *,
         auth: CredentialAuthCreateParam,
         name: str,
+        metadata: Dict[str, str] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
@@ -357,6 +373,9 @@ async def create(
           name: The name is trimmed before storage. It must contain 1 to 256 UTF-8 bytes after
               trimming.
 
+          metadata: Up to 16 string key-value pairs, with keys up to 64 and values up to 512
+              characters. Defaults to an empty map.
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -374,6 +393,7 @@ async def create(
                 {
                     "auth": auth,
                     "name": name,
+                    "metadata": metadata,
                 },
                 credential_create_params.CredentialCreateParams,
             ),
@@ -437,22 +457,26 @@ async def update(
         credential_id: str,
         *,
         vault_id: str,
-        auth: CredentialAuthRotateParam,
+        auth: CredentialAuthRotateParam | Omit = omit,
+        metadata: Dict[str, str] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
         extra_query: Query | None = None,
         extra_body: Body | None = None,
         timeout: float | httpx2.Timeout | None | NotGiven = not_given,
     ) -> Credential:
-        """
-        Rotates a vault credential's write-only secret and returns only credential
-        metadata. See
+        """Updates credential metadata or rotates its write-only secret.
+
+        See
         [vaults](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults).
 
         Args:
           auth: Replacement values for the credential's existing authentication method.
 
+          metadata: Replaces all metadata. Omit to preserve it, or pass {} to clear it. Up to 16
+              string key-value pairs, with keys up to 64 and values up to 512 characters.
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -470,7 +494,13 @@ async def update(
             path_template(
                 "/vaults/{vault_id}/credentials/{credential_id}", vault_id=vault_id, credential_id=credential_id
             ),
-            body=await async_maybe_transform({"auth": auth}, credential_update_params.CredentialUpdateParams),
+            body=await async_maybe_transform(
+                {
+                    "auth": auth,
+                    "metadata": metadata,
+                },
+                credential_update_params.CredentialUpdateParams,
+            ),
             options=make_request_options(
                 extra_headers=extra_headers,
                 extra_query=extra_query,

src/openai/types/beta/agents/vaults/credential.py

@@ -1,5 +1,6 @@
 # File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details.
 
+from typing import Dict
 from typing_extensions import Literal
 
 from ....._models import BaseModel
@@ -20,6 +21,9 @@ class Credential(BaseModel):
     created_at: int
     """The Unix timestamp, in seconds, when the credential was created."""
 
+    metadata: Dict[str, str]
+    """Application-defined key-value pairs associated with this credential."""
+
     name: str
     """The human-readable name of the credential."""
 

src/openai/types/beta/agents/vaults/credential_create_params.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from typing import Dict
 from typing_extensions import Required, TypedDict
 
 from .credential_auth_create_param import CredentialAuthCreateParam
@@ -18,3 +19,9 @@ class CredentialCreateParams(TypedDict, total=False):
 
     It must contain 1 to 256 UTF-8 bytes after trimming.
     """
+
+    metadata: Dict[str, str]
+    """
+    Up to 16 string key-value pairs, with keys up to 64 and values up to 512
+    characters. Defaults to an empty map.
+    """

src/openai/types/beta/agents/vaults/credential_update_params.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from typing import Dict
 from typing_extensions import Required, TypedDict
 
 from .credential_auth_rotate_param import CredentialAuthRotateParam
@@ -12,5 +13,12 @@
 class CredentialUpdateParams(TypedDict, total=False):
     vault_id: Required[str]
 
-    auth: Required[CredentialAuthRotateParam]
+    auth: CredentialAuthRotateParam
     """Replacement values for the credential's existing authentication method."""
+
+    metadata: Dict[str, str]
+    """Replaces all metadata.
+
+    Omit to preserve it, or pass {} to clear it. Up to 16 string key-value pairs,
+    with keys up to 64 and values up to 512 characters.
+    """

src/openai/types/beta/beta_web_search_preview_tool.py

@@ -9,7 +9,10 @@
 
 
 class UserLocation(BaseModel):
-    """The user's location."""
+    """The approximate location of the user.
+
+    If omitted or null, defaults to the United States. To avoid this fallback, pass `{"type": "approximate"}` without location fields. To localize results, provide the relevant location fields.
+    """
 
     type: Literal["approximate"]
     """The type of location approximation. Always `approximate`."""
@@ -55,4 +58,9 @@ class BetaWebSearchPreviewTool(BaseModel):
     """
 
     user_location: Optional[UserLocation] = None
-    """The user's location."""
+    """The approximate location of the user.
+
+    If omitted or null, defaults to the United States. To avoid this fallback, pass
+    `{"type": "approximate"}` without location fields. To localize results, provide
+    the relevant location fields.
+    """