From a294b970cdfc098345933176230441a5377fc3ed Mon Sep 17 00:00:00 2001
From: Jiwon Kim <jiwon@openai.com>
Date: Thu, 18 Dec 2025 20:23:20 -0800
Subject: [PATCH 1/2] attachment upload method

---
 chatkit/types.py | 24 +++++++++++++++++++++---
 1 file changed, 21 insertions(+), 3 deletions(-)

diff --git a/chatkit/types.py b/chatkit/types.py
index a0ceeea..48d7961 100644
--- a/chatkit/types.py
+++ b/chatkit/types.py
@@ -726,16 +726,34 @@ class ToolChoice(BaseModel):
     id: str
 
 
+class AttachmentUploadDescriptor(BaseModel):
+    """Two-phase upload instructions."""
+
+    url: AnyUrl
+    method: Literal["put", "post"]
+    """The HTTP method to use when uploading the file for two-phase upload."""
+    headers: dict[str, str] = Field(default_factory=dict)
+    """Optional headers to include in the upload request."""
+
+
 class AttachmentBase(BaseModel):
     """Base metadata shared by all attachments."""
 
     id: str
     name: str
     mime_type: str
-    upload_url: AnyUrl | None = None
+    upload_url: AnyUrl | None = Field(
+        default=None,
+        deprecated=True,
+        description="""This field is still supported but will
+            be removed in the next major version update. Please
+            use the `upload_descriptor` field instead.""",
+    )
+    upload_descriptor: AttachmentUploadDescriptor | None = None
     """
-    The URL to upload the file, used for two-phase upload.
-    Should be set to None after upload is complete or when using direct upload where uploading happens when creating the attachment object.
+    Two-phase upload instructions.
+    Should be set to None after upload is complete or when using direct upload
+    where uploading happens when creating the attachment object.
     """
 
 

From f0b1f904ccb47acb962028b01419b856dd348aa7 Mon Sep 17 00:00:00 2001
From: Jiwon Kim <jiwon@openai.com>
Date: Fri, 19 Dec 2025 09:45:41 -0800
Subject: [PATCH 2/2] remove deprecated field; make ChatKitServer handle
 attachment saving for 2-phase upload

---
 chatkit/server.py | 1 +
 chatkit/types.py  | 7 -------
 2 files changed, 1 insertion(+), 7 deletions(-)

diff --git a/chatkit/server.py b/chatkit/server.py
index 9d82b64..20a9f88 100644
--- a/chatkit/server.py
+++ b/chatkit/server.py
@@ -435,6 +435,7 @@ async def _process_non_streaming(
                 attachment = await attachment_store.create_attachment(
                     request.params, context
                 )
+                await self.store.save_attachment(attachment, context=context)
                 return self._serialize(attachment)
             case AttachmentsDeleteReq():
                 attachment_store = self._get_attachment_store()
diff --git a/chatkit/types.py b/chatkit/types.py
index 48d7961..8263cb3 100644
--- a/chatkit/types.py
+++ b/chatkit/types.py
@@ -742,13 +742,6 @@ class AttachmentBase(BaseModel):
     id: str
     name: str
     mime_type: str
-    upload_url: AnyUrl | None = Field(
-        default=None,
-        deprecated=True,
-        description="""This field is still supported but will
-            be removed in the next major version update. Please
-            use the `upload_descriptor` field instead.""",
-    )
     upload_descriptor: AttachmentUploadDescriptor | None = None
     """
     Two-phase upload instructions.