Python SDK monday.com (monday-api-python-sdk) zapewnia modułowy sposób korzystania z interfejsu GraphQL API monday.com w aplikacjach napisanych w Pythonie. Opakowuje bibliotekę requests i zawiera gotowe operacje pogrupowane w osobnych modułach, automatyczną deserializację odpowiedzi za pomocą dacite, wbudowaną logikę ponawiania żądań oraz automatyczne wersjonowanie API.

Pakiet	Zastosowanie	Najnowsza wersja
monday-api-python-sdk	Klient API, typowane modele odpowiedzi, gotowe operacje	1.6.5

---

Instalacja

pip install monday-api-python-sdk

Pakiet obsługuje Python 3.7 lub nowszy.

Zależności

SDK korzysta z requests i dacite. Te biblioteki są instalowane automatycznie.

---

MondayClient

MondayClient to główny punkt wejścia. Wymaga tokenu API i opcjonalnie przyjmuje niestandardowe nagłówki oraz konfigurację.

Tworzenie klienta

from monday_sdk import MondayClient

client = MondayClient(token="<YOUR_API_TOKEN>")

Parametry konstruktora

Parametr	Typ	Wymagany	Wartość domyślna	Opis
token	str	Tak	-	Twój token API monday.com (osobisty lub OAuth). Jest wysyłany w nagłówku Authorization.
headers	dict	Nie	{"API-Version": "2026-01"}	Niestandardowe nagłówki wysyłane z każdym żądaniem. Nagłówek API-Version jest ustawiany automatycznie, jeśli nie zostanie zastąpiony.
debug_mode	bool	Nie	False	Gdy wartość wynosi True, wyświetla surowe zapytanie i odpowiedź dla każdego wywołania API. Przydatne podczas tworzenia aplikacji.
max_retry_attempts	int	Nie	4	Maksymalna liczba ponowień nieudanych żądań (przekroczenie limitu zapytań, wyjątki dotyczące złożoności, błędy serwera).

client = MondayClient(
    token="<YOUR_API_TOKEN>",
    debug_mode=True,
    max_retry_attempts=6,
)

Moduły klienta

Klient grupuje operacje w moduły. Każdy moduł odpowiada za określony obszar API:

Moduł	Dostęp	Opis
client.boards	BoardModule	Pobieranie tablic i elementów oraz informacji o kolumnach.
client.items	ItemModule	Tworzenie, aktualizowanie, usuwanie i archiwizowanie elementów. Zmiana wartości kolumn. Przesyłanie plików.
client.updates	UpdateModule	Tworzenie, usuwanie i pobieranie aktualizacji (komentarzy) w elementach i na tablicach.
client.activity_logs	ActivityLogModule	Pobieranie dzienników aktywności z tablic, z opcjonalnym filtrowaniem według daty.
client.docs	DocsModule	Pobieranie zawartości i bloków dokumentów monday.
client.custom	CustomModule	Wykonywanie dowolnych zapytań GraphQL.

---

Operacje na tablicach

Moduł client.boards udostępnia metody pobierania tablic i ich elementów.

Pobieranie tablic

from monday_sdk import MondayClient

client = MondayClient(token="<YOUR_API_TOKEN>")

response = client.boards.fetch_boards(limit=10)

for board in response.data.boards:
    print(f"{board.id}: {board.name}")

Parametry

Parametr	Typ	Wartość domyślna	Opis
limit	int	50	Liczba tablic do zwrócenia.
page	int	None	Numer strony w paginacji.
ids	list[int]	None	Filtrowanie według konkretnych identyfikatorów tablic.
board_kind	BoardKind	None	Filtrowanie według typu tablicy (public, private, share).
state	BoardState	None	Filtrowanie według stanu (active, archived, deleted, all).
order_by	BoardsOrderBy	None	Kolejność sortowania (created_at lub used_at).

Pobieranie tablicy według identyfikatora

response = client.boards.fetch_boards_by_id(board_id=12345)
board = response.data.boards[0]
print(board.name)

Pobieranie wszystkich elementów z tablicy

Ta metoda automatycznie pobiera kolejne strony ze wszystkimi elementami, korzystając z paginacji opartej na kursorze. Uwzględnia limity złożoności i automatycznie wstrzymuje działanie między stronami.

items = client.boards.fetch_all_items_by_board_id(board_id=12345)

for item in items:
    print(f"{item.name} (updated: {item.updated_at})")
    for col in item.column_values:
        print(f"  {col.column.id}: {col.text}")

Parametry

Parametr	Typ	Wartość domyślna	Opis
board_id	int \| str	-	Identyfikator tablicy, z której chcesz pobrać elementy.
query_params	dict	None	Opcjonalne parametry zapytania służące do filtrowania.
limit	int	500	Liczba elementów na stronę.

Pobieranie elementów według daty aktualizacji

Przydatne przy synchronizacji przyrostowej - pobiera tylko elementy zmodyfikowane w określonym przedziale dat.

items = client.boards.fetch_item_by_board_id_by_update_date(
    board_id=12345,
    updated_after="2026-01-01T00:00:00Z",
    updated_before="2026-04-01T00:00:00Z",
)

Pobieranie kolumn

response = client.boards.fetch_columns_by_board_id(board_id=12345)

for col in response.data.boards[0].columns:
    print(f"{col.id} ({col.type}): {col.title}")

---

Operacje na elementach

Moduł client.items udostępnia metody tworzenia, pobierania i aktualizowania elementów oraz zarządzania nimi.

Tworzenie elementu

from monday_sdk import MondayClient

client = MondayClient(token="<YOUR_API_TOKEN>")

response = client.items.create_item(
    board_id=12345,
    group_id="topics",
    item_name="New task from Python SDK",
)

print(f"Created item: {response.data.create_item.id}")

Dodawanie wartości kolumn

column_values = {
    "status": "Working on it",
    "date_column": "2026-04-15",
    "text_column": "Important task",
}

response = client.items.create_item(
    board_id=12345,
    group_id="topics",
    item_name="Task with columns",
    column_values=column_values,
    create_labels_if_missing=True,
)

📘 Formaty wartości kolumn

W przypadku prostych kolumn tekstowych i kolumn statusu przekaż wartość jako ciąg znaków. W przypadku kolumn o bardziej złożonej strukturze przekaż słownik zgodny z oczekiwanym formatem JSON danej kolumny. Szczegółowe informacje o poszczególnych typach kolumn znajdziesz w dokumentacji wartości kolumn.

Tworzenie podelementu

response = client.items.create_subitem(
    parent_item_id=67890,
    subitem_name="Subtask from SDK",
    column_values={"status": "Done"},
)

Zmiana wartości kolumn

Prosta wartość tekstowa

client.items.change_simple_column_value(
    board_id=12345,
    item_id=67890,
    column_id="text_column",
    value="Updated via SDK",
)

Kolumna statusu

client.items.change_status_column_value(
    board_id=12345,
    item_id=67890,
    column_id="status",
    value="Done",
)

Kolumna daty

from datetime import datetime

client.items.change_date_column_value(
    board_id=12345,
    item_id=67890,
    column_id="date_column",
    timestamp=datetime(2026, 4, 15, 10, 30, 0),
)

Niestandardowa wartość kolumny (JSON)

W przypadku typów kolumn wymagających struktury JSON (np. pole wyboru lub lista rozwijana):

client.items.change_custom_column_value(
    board_id=12345,
    item_id=67890,
    column_id="checkbox_column",
    value={"checked": True},
)

Jednoczesna zmiana wartości wielu kolumn

client.items.change_multiple_column_values(
    board_id=12345,
    item_id=67890,
    column_values={
        "status": {"label": "Working on it"},
        "text_column": "Updated text",
        "date_column": {"date": "2026-04-15"},
    },
    create_labels_if_missing=True,
)

Pobieranie elementów

Według wartości kolumny

response = client.items.fetch_items_by_column_value(
    board_id=12345,
    column_id="status",
    value="Done",
    limit=50,
)

Według identyfikatora elementu

items = client.items.fetch_items_by_id(ids=[67890, 67891])

for item in items:
    print(f"{item.id}: {item.name}")

Przenoszenie, archiwizowanie i usuwanie elementów

client.items.move_item_to_group(item_id=67890, group_id="new_group")

client.items.archive_item_by_id(item_id=67890)

client.items.delete_item_by_id(item_id=67890)

---

Przesyłanie plików

SDK obsługuje przesyłanie plików do kolumn plików za pomocą osobnego punktu końcowego do przesyłania danych w formacie multipart.

from monday_sdk import MondayClient

client = MondayClient(token="<YOUR_API_TOKEN>")

result = client.items.upload_file_to_column(
    item_id=67890,
    column_id="files",
    file_path="./report.pdf",
)

print(result)

Parametry

Parametr	Typ	Wymagany	Opis
item_id	int \| str	Tak	Element, do którego chcesz przesłać plik.
column_id	str	Tak	Identyfikator kolumny plików.
file_path	str	Tak	Ścieżka do pliku na dysku.
mimetype	str	Nie	Typ MIME (np. 'application/pdf'). Jeśli go nie podasz, zostanie wykryty na podstawie rozszerzenia pliku.

⚠️ Ważne

Pliki są przesyłane przez osobny punkt końcowy API (https://api.monday.com/v2/file) i z użyciem żądania w formacie multipart. SDK obsługuje to automatycznie - wystarczy podać ścieżkę do pliku.

---

Operacje na aktualizacjach

Moduł client.updates obsługuje komentarze (aktualizacje) w elementach i na tablicach.

Tworzenie aktualizacji

from monday_sdk import MondayClient

client = MondayClient(token="<YOUR_API_TOKEN>")

response = client.updates.create_update(
    item_id=67890,
    update_value="Task completed ahead of schedule!",
)

Pobieranie aktualizacji elementu

response = client.updates.fetch_updates_for_item(item_id=67890, limit=50)

for update in response.data.items[0].updates:
    print(f"{update.creator.name}: {update.text_body}")

Pobieranie aktualizacji tablicy z filtrowaniem według daty

updates = client.updates.fetch_board_updates(
    board_ids="12345",
    updated_after="2026-01-01T00:00:00Z",
    updated_before="2026-04-01T00:00:00Z",
)

for update in updates:
    print(f"[{update.updated_at}] {update.text_body}")

📘 Filtrowanie według daty

Parametry from_date i to_date w zapytaniach o aktualizacje tablicy wymagają wersji API 2026-01 lub nowszej. Domyślną wersją SDK jest 2026-01. SDK dodatkowo filtruje daty po stronie klienta.

Usuwanie aktualizacji

client.updates.delete_update(item_id=67890)

---

Operacje na dziennikach aktywności

Moduł client.activity_logs pobiera aktywność na tablicach. Umożliwia opcjonalne filtrowanie według daty i typu zdarzenia.

Pobieranie wszystkich dzienników aktywności

from monday_sdk import MondayClient

client = MondayClient(token="<YOUR_API_TOKEN>")

logs = client.activity_logs.fetch_all_activity_logs_from_board(
    board_ids=12345,
    from_date="2026-01-01T00:00:00Z",
    to_date="2026-04-01T00:00:00Z",
)

for log in logs:
    print(f"[{log.event}] {log.data}")

Filtrowanie według typu zdarzenia

logs = client.activity_logs.fetch_all_activity_logs_from_board(
    board_ids=12345,
    events_filter=["create_pulse", "update_column_value"],
)

---

Operacje na dokumentach

Moduł client.docs pobiera zawartość dokumentów monday i automatycznie stronicuje ich bloki.

from monday_sdk import MondayClient

client = MondayClient(token="<YOUR_API_TOKEN>")

doc = client.docs.get_document_with_blocks(doc_id="35809248")

if doc:
    print(f"Document: {doc.name}")
    for block in doc.blocks:
        print(f"  [{block.type}] {block.content}")

---

Niestandardowe zapytania

Użyj client.custom, aby wykonać dowolne zapytanie lub mutację GraphQL, których nie obsługują wbudowane moduły.

Podstawowe zapytanie

from monday_sdk import MondayClient

client = MondayClient(token="<YOUR_API_TOKEN>")

response = client.custom.execute_custom_query("""
    query {
        boards(ids: [12345]) {
            id
            name
            columns { id title type }
        }
    }
""")

for board in response.data.boards:
    print(board.name)

Mutacja

response = client.custom.execute_custom_query("""
    mutation {
        create_item(
            board_id: 12345,
            group_id: "topics",
            item_name: "Created via custom query"
        ) {
            id
        }
    }
""")

📘 Kiedy używać niestandardowych zapytań

Używaj niestandardowych zapytań, gdy chcesz korzystać z funkcji API, których SDK jeszcze nie obsługuje, albo potrzebujesz precyzyjnie kontrolować strukturę zapytania GraphQL i zwracane pola.

---

Obsługa błędów

Typy wyjątków

SDK definiuje dwie klasy wyjątków:

Wyjątek	Opis
MondayError	Bazowa klasa wyjątków dla wszystkich błędów SDK.
MondayQueryError	Zgłaszany, gdy API zwróci błędy GraphQL. Zawiera listę original_errors z odpowiedzi.

Automatyczne ponawianie żądań

SDK automatycznie ponawia wszystkie nieudane żądania do max_retry_attempts razy (domyślnie: 4). Po wyczerpaniu wszystkich prób zgłasza standardowy wyjątek Exception z opisowym komunikatem.

Sytuacja	Działanie
Limit zapytań (HTTP 429)	Wstrzymuje działanie na 30 sekund, a następnie ponawia żądanie.
Wyjątek dotyczący złożoności	Wstrzymuje działanie na 2 sekundy, a następnie ponawia żądanie.
Błędy GraphQL	Ponawia żądanie do max_retry_attempts razy.
Błędy HTTP	Ponawia żądanie do max_retry_attempts razy.
504 Gateway Timeout	Ponawia żądanie, a następnie zgłasza opisowy błąd przekroczenia limitu czasu.

from monday_sdk import MondayClient

client = MondayClient(token="<YOUR_API_TOKEN>")

try:
    response = client.custom.execute_custom_query("""
        query { invalid_field }
    """)
except Exception as e:
    print(f"API error: {e}")

📘 Działanie ponawiania żądań

SDK ponawia wszystkie żądania, także te, które kończą się błędami zapytań GraphQL. Jeśli chcesz od razu przerwać działanie po błędnym zapytaniu zamiast ponawiać próbę, ustaw max_retry_attempts=1.

Maksymalną liczbę ponowień ustawisz za pomocą parametru max_retry_attempts w MondayClient.

Tryb debugowania

Włącz debug_mode, aby wyświetlać surowe zapytania i odpowiedzi:

client = MondayClient(
    token="<YOUR_API_TOKEN>",
    debug_mode=True,
)

---

Typy odpowiedzi

SDK deserializuje wszystkie odpowiedzi API do obiektów klas danych Pythona za pomocą dacite. Dzięki temu można odwoływać się do atrybutów i korzystać z autouzupełniania w IDE.

MondayApiResponse

Każda metoda modułu wywołująca API zwraca obiekt MondayApiResponse:

from monday_sdk import MondayClient, MondayApiResponse

client = MondayClient(token="<YOUR_API_TOKEN>")
response: MondayApiResponse = client.boards.fetch_boards(limit=5)

print(response.data.boards[0].name)
print(response.account_id)

Dostępne typy

Typ	Opis
MondayApiResponse	Pełna odpowiedź API zawierająca data i account_id.
Data	Główne dane odpowiedzi, w tym boards, items, complexity i docs.
Board	Tablica monday.com z polami items_page, updates, activity_logs, columns i groups.
Item	Element na tablicy z polami column_values, subitems i parent_item.
Column	Definicja kolumny (id, title, type).
ColumnValue	Wartość kolumny (value, text, display_value, column).
Group	Grupa na tablicy (id, title).
User	Użytkownik (id, name).
Update	Aktualizacja lub komentarz (id, text_body, creator, created_at, updated_at).
ActivityLog	Wpis w dzienniku aktywności (id, event, data, created_at, user_id).
ItemsPage	Stronicowana kolekcja elementów z kursorem cursor do paginacji.
Complexity	Informacje o złożoności zapytania (query, after).
Document	Dokument monday zawierający blocks, metadane i workspace.
DocumentBlock	Blok dokumentu (type, content, position).

Typy enum

Enum	Wartości
BoardKind	PUBLIC, PRIVATE, SHARE
BoardState	ALL, ACTIVE, ARCHIVED, DELETED
BoardsOrderBy	CREATED_AT, USED_AT
ColumnType	STATUS, TEXT, DATE, NUMBERS, PEOPLE, TIMELINE, CHECKBOX, DROPDOWN, FILE, LINK, LONG_TEXT, PHONE, EMAIL, RATING, TAGS i inne.
Operator	GREATER_THAN_OR_EQUALS, LESS_THAN_OR_EQUALS

Przykład importu

from monday_sdk import (
    MondayClient,
    MondayApiResponse,
    Board,
    Item,
    Column,
    ColumnValue,
    Update,
    ActivityLog,
)
from monday_sdk.types import BoardKind, BoardState, BoardsOrderBy, Operator
from monday_sdk.types.monday_enums import ColumnType

---

Wersjonowanie API

API monday.com jest wersjonowane kwartalnie. SDK automatycznie wysyła nagłówek API-Version z każdym żądaniem.

Wersja domyślna

Domyślną wersją SDK jest 2026-01. Jest ona ustawiona w pliku constants.py pakietu i stosowana za pomocą domyślnych nagłówków.

Format wersji

Wersje mają format yyyy-mm. Miesiąc przyjmuje jedną z wartości 01, 04, 07 lub 10 (nowa wersja jest wydawana co kwartał).

Cykl życia wersji

Etap	Opis
current	Aktualna stabilna wersja.
release_candidate	Kolejna wersja, dostępna w wersji zapoznawczej.
maintenance	Poprzednia wersja, która jest nadal obsługiwana.
deprecated	Wersja, która nie jest już obsługiwana i z czasem przestanie działać.

Zastępowanie wersji

Aby użyć innej wersji API, przekaż niestandardowe nagłówki:

client = MondayClient(
    token="<YOUR_API_TOKEN>",
    headers={"API-Version": "2025-10"},
)

---

Pełne przykłady

Pobieranie tablic i elementów

from monday_sdk import MondayClient

client = MondayClient(token="<YOUR_API_TOKEN>")

response = client.boards.fetch_boards(limit=5)
for board in response.data.boards:
    print(f"Board: {board.name} (ID: {board.id})")

items = client.boards.fetch_all_items_by_board_id(board_id=12345)
for item in items:
    print(f"  Item: {item.name}")
    for col in item.column_values:
        print(f"    {col.column.id}: {col.text}")

Tworzenie elementów i aktualizowanie kolumn

from monday_sdk import MondayClient

client = MondayClient(token="<YOUR_API_TOKEN>")

response = client.items.create_item(
    board_id=12345,
    group_id="topics",
    item_name="New feature request",
    column_values={
        "status": "Working on it",
        "text_column": "Description of the feature",
        "date_column": "2026-04-15",
    },
    create_labels_if_missing=True,
)

item_id = response.data.create_item.id

client.items.change_multiple_column_values(
    board_id=12345,
    item_id=item_id,
    column_values={
        "status": {"label": "Done"},
        "text_column": "Feature completed",
    },
)

Wzorzec synchronizacji przyrostowej

from monday_sdk import MondayClient

client = MondayClient(token="<YOUR_API_TOKEN>")

items = client.boards.fetch_item_by_board_id_by_update_date(
    board_id=12345,
    updated_after="2026-04-01T00:00:00Z",
    updated_before="2026-04-03T00:00:00Z",
)

for item in items:
    print(f"Modified: {item.name} at {item.updated_at}")

Wzorzec obsługi błędów

from monday_sdk import MondayClient

client = MondayClient(token="<YOUR_API_TOKEN>")

def safe_fetch_items(board_id):
    try:
        return client.boards.fetch_all_items_by_board_id(board_id=board_id)
    except Exception as e:
        error_msg = str(e)
        if "504" in error_msg:
            print("API timeout after retries. Try simplifying your query.")
        elif "429" in error_msg:
            print("Rate limited after retries. Wait and try again.")
        else:
            print(f"API error: {error_msg}")
        return []

Przesyłanie pliku

from monday_sdk import MondayClient

client = MondayClient(token="<YOUR_API_TOKEN>")

result = client.items.upload_file_to_column(
    item_id=67890,
    column_id="files",
    file_path="./document.pdf",
    mimetype="application/pdf",
)

print(f"Uploaded: {result}")

---

Skrócona lista

Lista metod modułów

BoardModule (client.boards)

Metoda	Opis
fetch_boards(limit, page, ids, board_kind, state, order_by)	Pobiera tablice z opcjonalnymi filtrami.
fetch_boards_by_id(board_id)	Pobiera jedną tablicę według identyfikatora.
fetch_all_items_by_board_id(board_id, query_params, limit)	Pobiera wszystkie elementy z automatyczną paginacją.
fetch_item_by_board_id_by_update_date(board_id, updated_after, updated_before, limit)	Pobiera elementy zmodyfikowane w określonym przedziale dat.
fetch_columns_by_board_id(board_id)	Pobiera definicje kolumn tablicy.

ItemModule (client.items)

Metoda	Opis
create_item(board_id, group_id, item_name, column_values, create_labels_if_missing)	Tworzy nowy element.
create_subitem(parent_item_id, subitem_name, column_values, create_labels_if_missing)	Tworzy podelement.
fetch_items_by_column_value(board_id, column_id, value, limit, cursor)	Wyszukuje elementy według wartości kolumny.
fetch_items_by_id(ids)	Pobiera elementy według ich identyfikatorów.
change_simple_column_value(board_id, item_id, column_id, value)	Ustawia wartość kolumny tekstowej.
change_status_column_value(board_id, item_id, column_id, value)	Ustawia etykietę kolumny statusu.
change_date_column_value(board_id, item_id, column_id, timestamp)	Ustawia wartość kolumny daty (przekaż obiekt datetime).
change_custom_column_value(board_id, item_id, column_id, value)	Ustawia wartość dowolnej kolumny za pomocą słownika JSON.
change_multiple_column_values(board_id, item_id, column_values, create_labels_if_missing)	Jednocześnie ustawia wartości wielu kolumn.
move_item_to_group(item_id, group_id)	Przenosi element do innej grupy.
archive_item_by_id(item_id)	Archiwizuje element.
delete_item_by_id(item_id)	Trwale usuwa element.
upload_file_to_column(item_id, column_id, file_path, mimetype)	Przesyła plik do kolumny plików.

UpdateModule (client.updates)

Metoda	Opis
create_update(item_id, update_value)	Tworzy aktualizację (komentarz) w elemencie.
delete_update(item_id)	Usuwa aktualizację.
fetch_updates(limit, page)	Pobiera aktualizacje z paginacją.
fetch_updates_for_item(item_id, limit)	Pobiera aktualizacje określonego elementu.
fetch_board_updates(board_ids, updated_after, updated_before)	Pobiera wszystkie aktualizacje z tablicy z filtrowaniem według daty.
fetch_board_updates_page(board_id, limit, page, from_date, to_date)	Pobiera jedną stronę aktualizacji tablicy.

ActivityLogModule (client.activity_logs)

Metoda	Opis
fetch_activity_logs_from_board(board_ids, page, limit, from_date, to_date)	Pobiera stronę dziennika aktywności.
fetch_all_activity_logs_from_board(board_ids, from_date, to_date, limit, events_filter)	Pobiera wszystkie wpisy dziennika aktywności z automatyczną paginacją i opcjonalnym filtrowaniem według zdarzeń.

DocsModule (client.docs)

Metoda	Opis
get_document_with_blocks(doc_id)	Pobiera dokument ze wszystkimi blokami (automatyczna paginacja).

CustomModule (client.custom)

Metoda	Opis
execute_custom_query(custom_query)	Wykonuje dowolne zapytanie lub mutację GraphQL.