### Install Monday API Setup Library

Source: https://github.com/mondaycom/monday-graphql-api/blob/main/packages/setup-api/README.md

Run this command in a bash-like environment in the root directory of your project to install the library. Not compatible with Windows Command Prompt.

```bash
npx @mondaydotcomorg/setup-api 
```

--------------------------------

### Install Monday GraphQL JS SDK

Source: https://github.com/mondaycom/monday-graphql-api/blob/main/packages/api/README.md

Install the SDK using npm. This command is used for project setup.

```bash
npm install @mondaydotcomorg/api
```

--------------------------------

### Install monday-graphql-api-types

Source: https://github.com/mondaycom/monday-graphql-api/blob/main/packages/api-types/README.md

Install the package using npm. This is a development dependency.

```bash
npm install --save-dev @mondaydotcomorg/api-types
```

--------------------------------

### Run API Setup Commands

Source: https://context7.com/mondaycom/monday-graphql-api/llms.txt

Commands to download the API schema and generate TypeScript types.

```bash
npm run fetch:schema  # Download latest monday.com API schema
npm run codegen       # Generate TypeScript types from your queries
```

--------------------------------

### Setup API CLI Tool

Source: https://context7.com/mondaycom/monday-graphql-api/llms.txt

Initialize the development environment and generate types using the CLI tool.

```bash
# Run the setup wizard in your project root
npx @mondaydotcomorg/setup-api

# This will:
# - Install required dependencies (@graphql-codegen/cli, etc.)
# - Create codegen.yml configuration
# - Create graphql.config.yml for IDE support
# - Add example queries in src/queries.graphql.ts
# - Add npm scripts to package.json

# After setup, fetch the schema and generate types
npm run fetch:generate
```

--------------------------------

### Build All Packages with Yarn

Source: https://github.com/mondaycom/monday-graphql-api/blob/main/README.md

Use this command to build all packages within the monorepo. Ensure you have Yarn installed.

```bash
yarn build
```

--------------------------------

### Install Project Rules for Cursor with Degit

Source: https://github.com/mondaycom/monday-graphql-api/blob/main/llm-context/README.md

Clone the LLM context rules into the .cursor/rules directory to configure project-specific rules in Cursor.

```bash
npx degit https://github.com/mondaycom/monday-graphql-api/llm-context/rules .cursor/rules
```

--------------------------------

### Install GraphQL Extension for VS Code via CLI

Source: https://github.com/mondaycom/monday-graphql-api/blob/main/packages/setup-api/README.md

Use this command to install the GraphQL extension for Visual Studio Code directly from the command line.

```bash
code --install-extension GraphQL.vscode-graphql
```

--------------------------------

### Example GraphQL Query Usage

Source: https://github.com/mondaycom/monday-graphql-api/blob/main/packages/setup-api/README.md

Demonstrates how to use the ApiClient from the monday api sdk to make a GraphQL query for boards. Ensure you replace placeholder values with your actual board ID and API token.

```typescript
const client = new ApiClient({token: '<API-TOKEN>'}); // From the monday api sdk @mondaydotcomorg/api

const queryVariables: QueryBoardsArgs = { ids: ["your_board_id"] }; // replace with your board id
const queryData = await client.request<GetBoardsQuery>(exampleQuery, queryVariables);
```

--------------------------------

### Run Fetch Schema and Codegen Scripts

Source: https://github.com/mondaycom/monday-graphql-api/blob/main/packages/setup-api/README.md

Execute this command to fetch the Monday API schema and generate types for your queries and mutations. This should be run after installation and whenever queries change.

```bash
npm run fetch:generate
```

--------------------------------

### Start Development Mode with Yarn

Source: https://github.com/mondaycom/monday-graphql-api/blob/main/README.md

Initiate the development mode for the monorepo using this Yarn command. This typically enables features like hot-reloading or watch mode.

```bash
yarn dev
```

--------------------------------

### Example GraphQL Mutation Usage

Source: https://github.com/mondaycom/monday-graphql-api/blob/main/packages/setup-api/README.md

Shows how to use the ApiClient to perform a GraphQL mutation to create an item on a Monday board. Replace placeholder values with your board ID, group ID, and desired item name.

```typescript
const mutationVariables: CreateItemMutationVariables = {
boardId: "your_board_id", // replace with your board id
groupId: "your_group_id", // replace with your group id
itemName: "Im using my own queries!",
};
const mutationData = await client.request<CreateItemMutation>(exampleMutation, mutationVariables);
```

--------------------------------

### Run Codegen Script

Source: https://github.com/mondaycom/monday-graphql-api/blob/main/packages/setup-api/README.md

Run this command to regenerate types after modifying your GraphQL queries or mutations. This command is part of the scripts added by the setup library.

```bash
npm run codegen
```

--------------------------------

### Define User Type

Source: https://github.com/mondaycom/monday-graphql-api/blob/main/packages/api/README.md

Example of using the exported `User` type from the SDK for defining user objects. This enhances code readability and type safety.

```typescript
import { User } from '@mondaydotcomorg/api';

const user: User = {
    id: '123',
    name: 'John Doe',
    email: 'john.doe@someorg.com'
}
```

--------------------------------

### Pre-built SDK Operations for Common Tasks

Source: https://context7.com/mondaycom/monday-graphql-api/llms.txt

Use these pre-built operations for common tasks like getting user info, creating items, and changing column values. Ensure you have initialized the ApiClient with your API token.

```typescript
import { ApiClient } from '@mondaydotcomorg/api';

const client = new ApiClient({ token: process.env.MONDAY_API_TOKEN });

// Get current user information
const meResult = await client.operations.getMeOp();
console.log(meResult.me); // { id, name, email }

// Create a new item on a board
const createResult = await client.operations.createItemOp({
  boardId: '1234567890',
  groupId: 'new_group',
  itemName: 'My New Task'
});
console.log(createResult.create_item); // { id: '9876543210', name: 'My New Task' }

// Change a column value (JSON format)
const changeResult = await client.operations.changeColumnValueOp({
  boardId: '1234567890',
  itemId: '9876543210',
  columnId: 'status',
  value: JSON.stringify({ label: 'Done' })
});

// Change a simple column value (string format)
const simpleChange = await client.operations.changeSimpleColumnValueOp({
  boardId: '1234567890',
  itemId: '9876543210',
  columnId: 'text',
  value: 'Hello, world!'
});

// Change multiple column values at once
const multiChange = await client.operations.changeMultipleColumnValuesOp({
  boardId: '1234567890',
  itemId: '9876543210',
  columnValues: JSON.stringify({
    status: { label: 'Working on it' },
    text: 'Updated text',
    numbers: 42
  })
});

// Get board items
const boardItems = await client.operations.getBoardItemsOp({
  ids: ['1234567890']
});
console.log(boardItems.boards?.[0]?.items_page.items);

// Get board groups
const boardGroups = await client.operations.getBoardGroupsOp({
  ids: ['1234567890']
});
console.log(boardGroups.boards?.[0]?.groups);
```

--------------------------------

### client.rawRequest - Get Full Response with Metadata

Source: https://context7.com/mondaycom/monday-graphql-api/llms.txt

The `rawRequest` method returns the complete GraphQL response including data, errors, and extensions. Useful when you need access to error details or response metadata.

```APIDOC
## client.rawRequest - Get Full Response with Metadata

### Description
The `rawRequest` method returns the complete GraphQL response including data, errors, and extensions. Useful when you need access to error details or response metadata.

### Request Example
```typescript
import { ApiClient, ClientError } from '@mondaydotcomorg/api';

const client = new ApiClient({
  token: process.env.MONDAY_API_TOKEN,
  requestConfig: { errorPolicy: 'all' }
});

// Raw request returns { data, errors, extensions }
const response = await client.rawRequest<{ boards: Array<{ id: string; name: string }> }>
  (`query { boards(ids: [123456]) { id name } }`,
  undefined,
  { timeoutMs: 15000 });

console.log(response.data?.boards);
console.log(response.errors); // GraphQL errors if any
console.log(response.extensions); // Response metadata
```
```

--------------------------------

### Change Text Column Value

Source: https://github.com/mondaycom/monday-graphql-api/blob/main/packages/api/README.md

Example of changing a text column's value using the SDK's operations. Ensure you provide the correct board ID, item ID, and column ID.

```typescript
// Example how to change a text column
const changeTextColumn = await client.operations.changeColumnValueOp({
    boardId: "your_board_id",
    itemId: "your_item_id",
    columnId: "text",
    value: JSON.stringify("Hello, world!"),
});
```

--------------------------------

### Change Status Column Value

Source: https://github.com/mondaycom/monday-graphql-api/blob/main/packages/api/README.md

Example of changing a status column's value. Specify the board ID, item ID, column ID, and the desired status label.

```typescript
// Example how to change a status column
const changeStatusColumn = await client.operations.changeColumnValueOp({
    boardId: "your_board_id",
    itemId: "your_item_id",
    columnId: "project_status", // replace with your column id
    value: JSON.stringify({ label: "Done" }),
});
```

--------------------------------

### Initialize ApiClient

Source: https://github.com/mondaycom/monday-graphql-api/blob/main/packages/api/README.md

Initialize the ApiClient with your API token. This is the main entry point for SDK operations.

```typescript
import { ApiClient } from '@mondaydotcomorg/api';

const client = new ApiClient({token: '<API-TOKEN>'});
```

--------------------------------

### Clone LLM Context Rules with Degit

Source: https://github.com/mondaycom/monday-graphql-api/blob/main/llm-context/README.md

Use this command to download the LLM context rules to your local machine for use with AI coding assistants.

```bash
npx degit https://github.com/mondaycom/monday-graphql-api/llm-context/rules
```

--------------------------------

### ApiClient - Main Client Initialization

Source: https://context7.com/mondaycom/monday-graphql-api/llms.txt

The ApiClient class is the primary entry point for server-side API interactions. It requires an API token and supports optional configuration including API version, custom endpoint, and request settings.

```APIDOC
## ApiClient - Main Client Initialization

### Description
The `ApiClient` class is the primary entry point for server-side API interactions. It requires an API token and supports optional configuration including API version, custom endpoint, and request settings.

### Request Example
```typescript
import { ApiClient } from '@mondaydotcomorg/api';

// Basic initialization
const client = new ApiClient({
  token: process.env.MONDAY_API_TOKEN
});

// Advanced initialization with all options
const advancedClient = new ApiClient({
  token: process.env.MONDAY_API_TOKEN,
  apiVersion: '2026-01', // Format: yyyy-mm (01, 04, 07, or 10)
  endpoint: 'https://api.monday.com/v2', // Optional custom endpoint
  requestConfig: {
    errorPolicy: 'all', // 'none' (default), 'ignore', or 'all'
    headers: { 'Custom-Header': 'value' }
  }
});

// Get current user info using built-in operations
const me = await client.operations.getMeOp();
console.log(me.me); // { id: '123', name: 'John Doe', email: 'john@example.com' }
```
```

--------------------------------

### Initialize ApiClient

Source: https://context7.com/mondaycom/monday-graphql-api/llms.txt

Use ApiClient for server-side applications requiring an API token. Supports custom API versions, endpoints, and request configurations.

```typescript
import { ApiClient } from '@mondaydotcomorg/api';

// Basic initialization
const client = new ApiClient({
  token: process.env.MONDAY_API_TOKEN
});

// Advanced initialization with all options
const advancedClient = new ApiClient({
  token: process.env.MONDAY_API_TOKEN,
  apiVersion: '2026-01', // Format: yyyy-mm (01, 04, 07, or 10)
  endpoint: 'https://api.monday.com/v2', // Optional custom endpoint
  requestConfig: {
    errorPolicy: 'all', // 'none' (default), 'ignore', or 'all'
    headers: { 'Custom-Header': 'value' }
  }
});

// Get current user info using built-in operations
const me = await client.operations.getMeOp();
console.log(me.me); // { id: '123', name: 'John Doe', email: 'john@example.com' }
```

--------------------------------

### Freestyle GraphQL Query (With Types)

Source: https://github.com/mondaycom/monday-graphql-api/blob/main/packages/api/README.md

Execute freestyle GraphQL queries using the SDK's provided types for better type safety. Ensure the `Board` type is correctly imported or defined.

```typescript
// You can also use the types provided by the sdk 
const { boards } = await client.request<{ 
  boards: [Board]; 
}>(`query { boards(ids: some_id) { name } }`);
```

--------------------------------

### Run Tests with Yarn

Source: https://github.com/mondaycom/monday-graphql-api/blob/main/README.md

Execute all tests across the monorepo packages using this Yarn command. This is crucial for verifying code integrity.

```bash
yarn test
```

--------------------------------

### Use SeamlessApiClient for Client-Side Requests

Source: https://github.com/mondaycom/monday-graphql-api/blob/main/packages/api/README.md

Utilize SeamlessApiClient for authenticated requests within apps deployed on Monday.com without manual token management.

```typescript
import {
  Board,
} from "@mondaydotcomorg/api";

// Option A - using pre defined types
const seamlessApiClient = new SeamlessApiClient();
const { boards } = await client.request<{boards: [Board];}>(`query { boards(ids: some_id) { id name } }`);

// Option B - using your own types after integrating with @mondaydotcomorg/setup-api
import { GetBoardsQueryVariables, GetBoardsQuery } from "./generated/graphql";
const seamlessApiClient = new SeamlessApiClient();
const variables: GetBoardsQueryVariables = { ids: ["some_id"] };

export const getBoards = gql`
  query GetBoards($ids: [ID!]) {
    boards(ids: $ids) {
      id
      name
    }
  }
`;

try {
  const data = await seamlessApiClient.request<GetBoardsQuery>(getBoards, variables);
} catch (error) { 
  // If the error is from SeamlessApiClient, it will be of type SeamlessApiClientError, which you can import from our package. Also, error.type will also 'SeamlessApiClientError'.
  
  console.log(error.response.errors)
}
```

--------------------------------

### Execute Raw GraphQL Requests

Source: https://github.com/mondaycom/monday-graphql-api/blob/main/packages/api/README.md

Shows how to use rawRequest to access the full response structure including data, errors, and extensions.

```typescript
import { ApiClient, ClientError } from "@mondaydotcomorg/api";
import { GetBoardsQuery, GetBoardsQueryVariables } from "./generated/graphql";
import { exampleQuery } from "./queries.graphql";

async function getBoardDetails(): Promise<void> {
  try {
    const token = "<API_TOKEN>";
    const client = new ApiClient({ token });
    const queryVariables: GetBoardsQueryVariables = { ids: ["5901934630"] };
    const queryData = await client.rawRequest<GetBoardsQuery>(
      exampleQuery,
      queryVariables
    );

    console.log(queryData.data.boards);
  } catch (error) {
    if (error instanceof ClientError) {
      console.error(error.response.errors);
    } else {
      console.error(error);
    }
  }
}

getBoardDetails();
```

--------------------------------

### Utilize TypeScript Types

Source: https://context7.com/mondaycom/monday-graphql-api/llms.txt

Import entity types from the SDK to ensure type safety when working with monday.com objects.

```typescript
import type {
  User,
  Board,
  Item,
  Column,
  ColumnType,
  ColumnValue,
  Group,
  Workspace,
  Team,
  Update,
  Asset,
  BoardKind,
  State
} from '@mondaydotcomorg/api';

// Type-safe user object
const user: User = {
  id: '123',
  name: 'John Doe',
  email: 'john@example.com',
  enabled: true,
  url: 'https://example.monday.com/users/123',
  account: { id: '456', name: 'My Company', slug: 'my-company' }
};

// Column type enumeration
const columnTypes: ColumnType[] = [
  'text',
  'status',
  'date',
  'numbers',
  'people',
  'checkbox',
  'dropdown',
  'file',
  'timeline',
  'link'
];

// Board kind options
const boardKinds: BoardKind[] = ['public', 'private', 'share'];

// State options for filtering
const states: State[] = ['active', 'archived', 'deleted', 'all'];
```

--------------------------------

### Execute GraphQL Queries with client.request

Source: https://context7.com/mondaycom/monday-graphql-api/llms.txt

Executes arbitrary GraphQL queries and mutations with full type support. Allows passing variables, setting timeouts, and overriding API versions.

```typescript
import { ApiClient, Board, User } from '@mondaydotcomorg/api';

const client = new ApiClient({ token: process.env.MONDAY_API_TOKEN });

// Simple query
const { boards } = await client.request<{ boards: Board[] }>(
  `query { boards(ids: [123456]) { id name description } }`
);
console.log(boards[0].name);

// Query with variables
const { users } = await client.request<{ users: User[] }>(
  `query GetUsers($limit: Int!, $page: Int!) {
    users(limit: $limit, page: $page) {
      id
      name
      email
    }
  }`,
  { limit: 50, page: 1 }
);

// Query with timeout (max 60 seconds)
const { boards: timedBoards } = await client.request<{ boards: Board[] }>(
  `query { boards(ids: [123456]) { name items_count } }`,
  undefined,
  { timeoutMs: 20000 }
);

// Query with version override
const result = await client.request<{ boards: Board[] }>(
  `query { boards(ids: [123456]) { name } }`,
  undefined,
  { versionOverride: '2025-10' }
);
```

--------------------------------

### client.request - Execute GraphQL Queries

Source: https://context7.com/mondaycom/monday-graphql-api/llms.txt

The `request` method executes arbitrary GraphQL queries and mutations with full type support. It accepts a query string, optional variables, and request options including timeout and version override.

```APIDOC
## client.request - Execute GraphQL Queries

### Description
The `request` method executes arbitrary GraphQL queries and mutations with full type support. It accepts a query string, optional variables, and request options including timeout and version override.

### Request Example
```typescript
import { ApiClient, Board, User } from '@mondaydotcomorg/api';

const client = new ApiClient({ token: process.env.MONDAY_API_TOKEN });

// Simple query
const { boards } = await client.request<{ boards: Board[] }>
  (`query { boards(ids: [123456]) { id name description } }`);
console.log(boards[0].name);

// Query with variables
const { users } = await client.request<{ users: User[] }>
  (`query GetUsers($limit: Int!, $page: Int!) {
    users(limit: $limit, page: $page) {
      id
      name
      email
    }
  }`,
  { limit: 50, page: 1 });

// Query with timeout (max 60 seconds)
const { boards: timedBoards } = await client.request<{ boards: Board[] }>
  (`query { boards(ids: [123456]) { name items_count } }`,
  undefined,
  { timeoutMs: 20000 });

// Query with version override
const result = await client.request<{ boards: Board[] }>
  (`query { boards(ids: [123456]) { name } }`,
  undefined,
  { versionOverride: '2025-10' });
```
```

--------------------------------

### Implement Cursor-Based Pagination

Source: https://context7.com/mondaycom/monday-graphql-api/llms.txt

Fetches large datasets by iterating through pages using the cursor returned by items_page and next_items_page queries.

```typescript
import { ApiClient } from '@mondaydotcomorg/api';

const client = new ApiClient({ token: process.env.MONDAY_API_TOKEN });

interface Item {
  id: string;
  name: string;
  column_values: Array<{ id: string; value: string }>;
}

async function getAllBoardItems(boardId: string): Promise<Item[]> {
  const allItems: Item[] = [];

  // First request to get initial page
  const firstPage = await client.request<{
    boards: Array<{
      items_page: {
        cursor: string | null;
        items: Item[];
      };
    }>;
  }>(
    `query GetBoardItems($boardId: [ID!]!) {
      boards(ids: $boardId) {
        items_page(limit: 100) {
          cursor
          items {
            id
            name
            column_values {
              id
              value
            }
          }
        }
      }
    }`,
    { boardId: [boardId] }
  );

  let cursor = firstPage.boards[0]?.items_page.cursor;
  allItems.push(...(firstPage.boards[0]?.items_page.items || []));

  // Continue fetching while cursor exists
  while (cursor) {
    const nextPage = await client.request<{
      next_items_page: {
        cursor: string | null;
        items: Item[];
      };
    }>(
      `query GetNextItems($cursor: String!) {
        next_items_page(limit: 100, cursor: $cursor) {
          cursor
          items {
            id
            name
            column_values {
              id
              value
            }
          }
        }
      }`,
      { cursor }
    );

    allItems.push(...nextPage.next_items_page.items);
    cursor = nextPage.next_items_page.cursor;
  }

  return allItems;
}

// Usage
const items = await getAllBoardItems('1234567890');
console.log(`Fetched ${items.length} items`);
```

--------------------------------

### Perform Board and Item Mutations

Source: https://context7.com/mondaycom/monday-graphql-api/llms.txt

Use the ApiClient to execute GraphQL mutations for creating boards, groups, items, subitems, and managing item lifecycle states.

```typescript
import { ApiClient } from '@mondaydotcomorg/api';

const client = new ApiClient({ token: process.env.MONDAY_API_TOKEN });

// Create a new board
const newBoard = await client.request<{
  create_board: { id: string; name: string };
}>(
  `mutation CreateBoard($name: String!, $kind: BoardKind!) {
    create_board(board_name: $name, board_kind: $kind) {
      id
      name
    }
  }`,
  { name: 'My Project Board', kind: 'public' }
);

// Create a group in a board
const newGroup = await client.request<{
  create_group: { id: string; title: string };
}>(
  `mutation CreateGroup($boardId: ID!, $name: String!) {
    create_group(board_id: $boardId, group_name: $name) {
      id
      title
    }
  }`,
  { boardId: newBoard.create_board.id, name: 'Sprint 1' }
);

// Create an item with column values
const newItem = await client.request<{
  create_item: { id: string; name: string };
}>(
  `mutation CreateItem($boardId: ID!, $groupId: String!, $name: String!, $columnValues: JSON!) {
    create_item(
      board_id: $boardId,
      group_id: $groupId,
      item_name: $name,
      column_values: $columnValues
    ) {
      id
      name
    }
  }`,
  {
    boardId: newBoard.create_board.id,
    groupId: newGroup.create_group.id,
    name: 'Implement feature X',
    columnValues: JSON.stringify({
      status: { label: 'Working on it' },
      date: { date: '2024-12-31' },
      text: 'High priority task'
    })
  }
);

// Create a subitem
const subitem = await client.request<{
  create_subitem: { id: string; name: string };
}>(
  `mutation CreateSubitem($parentId: ID!, $name: String!, $columnValues: JSON) {
    create_subitem(
      parent_item_id: $parentId,
      item_name: $name,
      column_values: $columnValues
    ) {
      id
      name
    }
  }`,
  {
    parentId: newItem.create_item.id,
    name: 'Subtask 1',
    columnValues: JSON.stringify({ status: { label: 'Not Started' } })
  }
);

// Archive an item
await client.request(
  `mutation ArchiveItem($itemId: ID!) {
    archive_item(item_id: $itemId) { id }
  }`,
  { itemId: newItem.create_item.id }
);

// Delete an item
await client.request(
  `mutation DeleteItem($itemId: ID!) {
    delete_item(item_id: $itemId) { id }
  }`,
  { itemId: '9876543210' }
);
```

--------------------------------

### Freestyle GraphQL Query (No Types)

Source: https://github.com/mondaycom/monday-graphql-api/blob/main/packages/api/README.md

Execute freestyle GraphQL queries without using SDK types. This is useful for complex or custom queries.

```typescript
// Use the client to query monday's API freestyle WITHOUT TYPES -> Use @mondaydotcomorg/setup-api to setup typed project!
const boards = await client.request<{boards: [{ name: string }]}>(`query { boards(ids: some_id) { name } }`);
```

--------------------------------

### Automatic File Uploads

Source: https://context7.com/mondaycom/monday-graphql-api/llms.txt

The SDK automatically handles file uploads using multipart form data when File or Blob objects are detected. This is useful for uploading files to file columns or updates.

```typescript
import { ApiClient } from '@mondaydotcomorg/api';

const client = new ApiClient({ token: process.env.MONDAY_API_TOKEN });

// Create a file to upload
const file = new File([Buffer.from('Hello World!')], 'test.txt', { type: 'text/plain' });

// Upload file to a file column
const result = await client.request<{ 
  add_file_to_column: { id: string; name: string; url: string }
}>(
  `mutation ($file: File!, $itemId: ID!, $columnId: String!) {
    add_file_to_column(file: $file, item_id: $itemId, column_id: $columnId) {
      id
      name
      url
    }
  }`,
  {
    file,
    itemId: '9876543210',
    columnId: 'files'
  }
);

console.log(result.add_file_to_column);
// { id: '12345', name: 'test.txt', url: 'https://...' }

// Upload file to an update
const updateResult = await client.request<{ 
  add_file_to_update: { id: string; name: string }
}>(
  `mutation ($file: File!, $updateId: ID!) {
    add_file_to_update(file: $file, update_id: $updateId) {
      id
      name
    }
  }`,
  {
    file: new File([imageBuffer], 'screenshot.png', { type: 'image/png' }),
    updateId: '123456789'
  }
);

```

--------------------------------

### Use SeamlessApiClient for Browser Apps

Source: https://context7.com/mondaycom/monday-graphql-api/llms.txt

Utilizes the platform's internal messaging for authentication, eliminating the need for an explicit API token. Supports version overrides and custom timeouts for requests.

```typescript
import { SeamlessApiClient, SeamlessApiClientError, Board } from '@mondaydotcomorg/api';

// Initialize (no token needed - monday.com handles auth)
const seamlessClient = new SeamlessApiClient();

// Or with a specific API version
const versionedClient = new SeamlessApiClient('2026-01');

// Make a request
async function fetchBoards() {
  try {
    const result = await seamlessClient.request<{ boards: Board[] }>(
      `query GetBoards($ids: [ID!]) {
        boards(ids: $ids) {
          id
          name
          items_count
        }
      }`,
      { ids: ['1234567890'] }
    );

    return result.boards;
  } catch (error) {
    if (error instanceof SeamlessApiClientError) {
      console.error('API Error:', error.message);
      console.error('Errors:', error.response.errors);
      console.error('Partial Data:', error.response.data);
    }
    throw error;
  }
}

// Request with version override and custom timeout
const items = await seamlessClient.request<{ items: Array<{ id: string; name: string }> }>(
  `query { items(ids: [123, 456]) { id name } }`,
  undefined,
  '2025-10', // version override
  30000      // timeout in ms (default: 60000)
);
```

--------------------------------

### Define GraphQL Queries

Source: https://context7.com/mondaycom/monday-graphql-api/llms.txt

Define GraphQL queries and mutations using the gql tag for use with generated types.

```typescript
// src/queries.graphql.ts
import { gql } from 'graphql-tag';

export const getBoards = gql`
  query GetBoards($ids: [ID!]) {
    boards(ids: $ids) {
      id
      name
      items_count
    }
  }
`;

export const createItem = gql`
  mutation CreateItem($boardId: ID!, $groupId: String!, $itemName: String!) {
    create_item(board_id: $boardId, group_id: $groupId, item_name: $itemName) {
      id
      name
    }
  }
`;
```

--------------------------------

### Handle API Errors with ApiClient

Source: https://github.com/mondaycom/monday-graphql-api/blob/main/packages/api/README.md

Demonstrates catching and handling ClientError instances when using the standard request method.

```typescript
import { ApiClient, ClientError } from "@mondaydotcomorg/api";
import { GetBoardsQuery, GetBoardsQueryVariables } from "./generated/graphql";
import { exampleQuery } from "./queries.graphql";

async function getBoardDetails(): Promise<void> {
  try {
    const token = "<API_TOKEN>";
    const client = new ApiClient({ token });
    const queryVariables: GetBoardsQueryVariables = { ids: ["5901934630"] };
    const queryData = await client.request<GetBoardsQuery>(
      exampleQuery,
      queryVariables
    );

    console.log(queryData.boards);
  } catch (error) {
    if (error instanceof ClientError) {
      console.error(error.response.errors);
    } else {
      console.error(error);
    }
  }
}

getBoardDetails();
```

--------------------------------

### Execute Typed GraphQL Requests

Source: https://context7.com/mondaycom/monday-graphql-api/llms.txt

Use the ApiClient to execute queries with full TypeScript type safety.

```typescript
import { ApiClient } from '@mondaydotcomorg/api';
import { GetBoardsQuery, GetBoardsQueryVariables } from './generated/graphql';
import { getBoards } from './queries.graphql';

const client = new ApiClient({ token: process.env.MONDAY_API_TOKEN });

const variables: GetBoardsQueryVariables = { ids: ['1234567890'] };
const result = await client.request<GetBoardsQuery>(getBoards, variables);

// Full type safety - result.boards is properly typed
console.log(result.boards?.[0]?.name);
```

--------------------------------

### Fetch Current User Data

Source: https://github.com/mondaycom/monday-graphql-api/blob/main/packages/api/README.md

Use the operations provided by the SDK to fetch the current user's data.

```typescript
// Or use the operations provided by the SDK
const me = await client.operations.getMeOp();
```

--------------------------------

### Configure Error Policy

Source: https://github.com/mondaycom/monday-graphql-api/blob/main/packages/api/README.md

Configure the `errorPolicy` in the `ApiClient` constructor to handle GraphQL errors. Options include 'none' (default), 'ignore', and 'all'.

```typescript
const client = new ApiClient({token: '<API-TOKEN>', requestConfig: { errorPolicy: 'all' }});
```

--------------------------------

### File Upload using ApiClient

Source: https://github.com/mondaycom/monday-graphql-api/blob/main/packages/api/README.md

Upload files to a column using the ApiClient. Requires Node's `File` or `Blob` object and specifies the item ID and column ID for the upload.

```typescript
import { ApiClient } from '@mondaydotcomorg/api';

const client = new ApiClient({ token: '<API-TOKEN>' });

// Create a file to upload
const file = new File([Buffer.from('Hello World!')], 'test.txt', { type: 'text/plain' });

// Upload the file to a column
const result = await client.request(
  `mutation ($file: File!, $itemId: ID!, $columnId: String!) {
    add_file_to_column(file: $file, item_id: $itemId, column_id: $columnId) {
      id
      name
      url
    }
  }`,
  {
    file,
    itemId: 'your_item_id',
    columnId: 'files', // your file column id
  }
);

console.log(result.add_file_to_column);
```

--------------------------------

### Use User Type in TypeScript

Source: https://github.com/mondaycom/monday-graphql-api/blob/main/packages/api-types/README.md

Import and use the User type from the SDK in your TypeScript code. Ensure the imported type matches the expected structure for a user object.

```typescript
import type { User } from '@mondaydotcomorg/api-types';

const user: User = {
    id: '123',
    name: 'John Doe',
    email: 'john.doe@someorg.com'
}
```

--------------------------------

### GraphQL Query with Timeout

Source: https://github.com/mondaycom/monday-graphql-api/blob/main/packages/api/README.md

Configure a timeout for GraphQL requests to prevent excessively long operations. The timeout is specified in milliseconds.

```typescript
// You can also define timeout for requests
const { boards } = await client.request<{ 
  boards: [Board]; 
}>(`query { boards(ids: some_id) { name } }`, undefined, { timeoutMs: 20_000 });
```

--------------------------------

### Retrieve Full Response with client.rawRequest

Source: https://context7.com/mondaycom/monday-graphql-api/llms.txt

Returns the complete GraphQL response object, including data, errors, and extensions. Useful for debugging or accessing response metadata.

```typescript
import { ApiClient, ClientError } from '@mondaydotcomorg/api';

const client = new ApiClient({
  token: process.env.MONDAY_API_TOKEN,
  requestConfig: { errorPolicy: 'all' }
});

// Raw request returns { data, errors, extensions }
const response = await client.rawRequest<{ boards: Array<{ id: string; name: string }> }>(
  `query { boards(ids: [123456]) { id name } }`,
  undefined,
  { timeoutMs: 15000 }
);

console.log(response.data?.boards);
console.log(response.errors); // GraphQL errors if any
console.log(response.extensions); // Response metadata
```

--------------------------------

### Handle GraphQL API Errors with ApiClient

Source: https://context7.com/mondaycom/monday-graphql-api/llms.txt

Wraps API requests in try-catch blocks to distinguish between GraphQL-specific errors and network issues. Use ClientError to inspect response status and specific error messages like rate limits.

```typescript
import { ApiClient, ClientError } from '@mondaydotcomorg/api';

const client = new ApiClient({ token: process.env.MONDAY_API_TOKEN });

async function getBoardDetails(boardId: string) {
  try {
    const result = await client.request<{ boards: Array<{ id: string; name: string }> }>(
      `query GetBoard($ids: [ID!]!) {
        boards(ids: $ids) {
          id
          name
          items_count
        }
      }`,
      { ids: [boardId] }
    );

    return result.boards[0];
  } catch (error) {
    if (error instanceof ClientError) {
      // GraphQL-specific errors
      console.error('GraphQL Errors:', error.response.errors);
      console.error('Status:', error.response.status);

      // Check for specific error types
      const errors = error.response.errors || [];
      for (const err of errors) {
        if (err.message.includes('Rate limit')) {
          console.log('Rate limited - implement backoff');
        }
        if (err.message.includes('Not authorized')) {
          console.log('Check API token permissions');
        }
      }
    } else if (error instanceof Error) {
      // Network or timeout errors
      console.error('Network Error:', error.message);
    }
    throw error;
  }
}
```

--------------------------------

### Updating Various Column Types

Source: https://context7.com/mondaycom/monday-graphql-api/llms.txt

When updating column values, ensure the 'value' is correctly JSON-stringified according to the specific column type. The SDK handles the serialization, but the format must be accurate for each type.

```typescript
import { ApiClient } from '@mondaydotcomorg/api';

const client = new ApiClient({ token: process.env.MONDAY_API_TOKEN });
const boardId = '1234567890';
const itemId = '9876543210';

// Text column
await client.operations.changeColumnValueOp({
  boardId, itemId,
  columnId: 'text',
  value: JSON.stringify('Hello, world!')
});

// Status column (by label)
await client.operations.changeColumnValueOp({
  boardId, itemId,
  columnId: 'status',
  value: JSON.stringify({ label: 'Done' })
});

// Status column (by index)
await client.operations.changeColumnValueOp({
  boardId, itemId,
  columnId: 'status',
  value: JSON.stringify({ index: 1 })
});

// Date column
await client.operations.changeColumnValueOp({
  boardId, itemId,
  columnId: 'date',
  value: JSON.stringify({ date: '2024-12-31', time: '14:30:00' })
});

// People column
await client.operations.changeColumnValueOp({
  boardId, itemId,
  columnId: 'people',
  value: JSON.stringify({ personsAndTeams: [{ id: 12345, kind: 'person' }] })
});

// Numbers column
await client.operations.changeColumnValueOp({
  boardId, itemId,
  columnId: 'numbers',
  value: JSON.stringify(42.5)
});

// Checkbox column
await client.operations.changeColumnValueOp({
  boardId, itemId,
  columnId: 'checkbox',
  value: JSON.stringify({ checked: true })
});

// Dropdown column
await client.operations.changeColumnValueOp({
  boardId, itemId,
  columnId: 'dropdown',
  value: JSON.stringify({ labels: ['Option 1', 'Option 2'] })
});

// Link column
await client.operations.changeColumnValueOp({
  boardId, itemId,
  columnId: 'link',
  value: JSON.stringify({ url: 'https://monday.com', text: 'Monday.com' })
});
```

--------------------------------

### Set Request Timeout with ApiClient

Source: https://github.com/mondaycom/monday-graphql-api/blob/main/packages/api/CHANGELOG.MD

Use the `timeout` option in `RequestOptions` to define a timeout for `.request()` and `.rawRequest()` methods. This feature was added in version 13.0.0.

```javascript
import { ApiClient } from '@mondaydotcomorg/api';

const client = new ApiClient({token: '<API-TOKEN>'});

client.request('<QUERY>', undefined, { timeout: 20_000 })
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.