Merge pull request #36 from mondaycom/add-support-for-file-upload

Added support for uploading file into an item's column

Author: NoamGitHub

setup.py

@@ -15,7 +15,7 @@
 
 setup(
     name="monday-api-python-sdk",  # Required
-    version="1.5.4",  # Required
+    version="1.6.0",  # Required
     description="A Python SDK for interacting with Monday's GraphQL API",  # Optional
     long_description=long_description,  # Optional
     long_description_content_type="text/markdown",  # Optional (see note above)

src/monday_sdk/constants.py

@@ -1,4 +1,5 @@
 API_URL = "https://api.monday.com/v2"
+FILE_UPLOAD_URL = "https://api.monday.com/v2/file"
 API_VERSION = "2026-01"
 TOKEN_HEADER = "Authorization"
 MAX_COMPLEXITY = 10000000  # Monday's API complexity limit per minute

src/monday_sdk/graphql_handler.py

@@ -1,10 +1,12 @@
 import dacite
+import mimetypes
+import os
 import requests
 import json
 import time
 
-from .constants import API_URL, TOKEN_HEADER, DEFAULT_MAX_RETRY_ATTEMPTS
-from .types import MondayApiResponse
+from .constants import API_URL, FILE_UPLOAD_URL, TOKEN_HEADER, DEFAULT_MAX_RETRY_ATTEMPTS
+from .types import MondayApiResponse, FileInput
 from .exceptions import MondayQueryError
 
 
@@ -106,4 +108,53 @@ def _send(self, query: str):
         if self.token is not None:
             headers[TOKEN_HEADER] = self.token
 
-        return requests.request("POST", self.endpoint, headers=headers, json=payload)
+        return requests.request("POST", self.endpoint, headers=headers, json=payload)
+
+    def execute_multipart(self, query: str, file: FileInput) -> dict:
+        """
+        Execute a GraphQL mutation using multipart/form-data.
+
+        Used for mutations that require file uploads (e.g., add_file_to_column,
+        add_file_to_update). This follows the GraphQL multipart request specification.
+
+        Args:
+            query: The GraphQL mutation string (must accept a File! variable)
+            file: FileInput containing file details (name, path, optional filename/mimetype)
+
+        Returns:
+            The API response as a dictionary
+
+        Raises:
+            requests.HTTPError: If the API request fails
+        """
+        filename = file.filename or os.path.basename(file.file_path)
+        file_mimetype = file.mimetype
+        if file_mimetype is None:
+            file_mimetype, _ = mimetypes.guess_type(file.file_path)
+            file_mimetype = file_mimetype or 'application/octet-stream'
+
+        if self.debug_mode:
+            print(f"[debug_mode] executing multipart mutation with file: {filename}, mimetype: {file_mimetype}")
+
+        with open(file.file_path, 'rb') as f:
+            # Following the GraphQL multipart request spec
+            payload = {
+                'query': query,
+                'map': json.dumps({file.name: [f"variables.{file.name}"]})
+            }
+            files = [
+                (file.name, (filename, f, file_mimetype))
+            ]
+
+            response = requests.post(
+                FILE_UPLOAD_URL,
+                headers={TOKEN_HEADER: self.token},
+                data=payload,
+                files=files,
+            )
+
+        if self.debug_mode:
+            print(f"[debug_mode] multipart response: {response.status_code}, {response.text}")
+
+        response.raise_for_status()
+        return response.json()

src/monday_sdk/modules/items.py

@@ -1,7 +1,9 @@
-from typing import Union, Dict, Any, List
+from typing import Union, Dict, Any, List, Optional
 import datetime
+import os
 
 from ..graphql_handler import MondayGraphQL
+from ..types import FileInput
 from ..query_templates import create_item_query, get_item_query, change_column_value_query, get_item_by_id_query, update_multiple_column_values_query, create_subitem_query, delete_item_query, archive_item_query, move_item_to_group_query, change_simple_column_value_query
 from ..types import Item
 
@@ -101,3 +103,51 @@ def archive_item_by_id(self, item_id: Union[str, int]):
     def delete_item_by_id(self, item_id: Union[str, int]):
         query = delete_item_query(item_id)
         return self.client.execute(query)
+
+    def upload_file_to_column(
+        self,
+        item_id: Union[str, int],
+        column_id: str,
+        file_path: str,
+        mimetype: Optional[str] = None,
+    ) -> dict:
+        """
+        Upload a file to a file column on an item.
+
+        Note: Unlike other column methods, this uses a different API endpoint
+        (https://api.monday.com/v2/file) and does not require board_id.
+
+        Args:
+            item_id: The ID of the item to add the file to
+            column_id: The ID of the file column
+            file_path: Path to the file to upload
+            mimetype: Optional MIME type (e.g., 'audio/mpeg', 'video/mp4').
+                      If not provided, will be auto-detected from the file extension.
+
+        Returns:
+            The API response containing the uploaded asset info
+
+        Raises:
+            FileNotFoundError: If the file doesn't exist
+            requests.HTTPError: If the API request fails
+        """
+        if not os.path.exists(file_path):
+            raise FileNotFoundError(f"File not found: {file_path}")
+
+        mutation = '''mutation ($file: File!) {
+            add_file_to_column(item_id: %s, column_id: "%s", file: $file) {
+                id
+                name
+                url
+                file_extension
+                file_size
+            }
+        }''' % (item_id, column_id)
+
+        file_input = FileInput(
+            name="file",
+            file_path=file_path,
+            mimetype=mimetype,
+        )
+
+        return self.client.execute_multipart(mutation, file_input)

src/monday_sdk/types/__init__.py

@@ -16,3 +16,4 @@
     Document,
 )
 from .monday_enums import BoardKind, BoardState, BoardsOrderBy, Operator
+from .file_input import FileInput

src/monday_sdk/types/file_input.py

@@ -0,0 +1,12 @@
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class FileInput:
+    """Represents a file to be uploaded via multipart/form-data."""
+    name: str                           # The variable name in the GraphQL mutation (e.g., "file")
+    file_path: str                      # Path to the file
+    filename: Optional[str] = None      # Override filename (defaults to basename of file_path)
+    mimetype: Optional[str] = None      # MIME type (auto-detected if not provided)
+