Setup

API Setup

Bootstrap a project to use the monday.com public GraphQL API with the @mondaydotcomorg/api SDK.

Scope

• Helps external developers set up a new or existing Node.js project for the monday.com API
• Does NOT set up monday-code apps or internal platform API — those are separate plugins

Prerequisites

• Node.js 18+ installed
• A monday.com API token

To get a personal API token:

1. In monday.com, click your profile picture → Developers → API
2. Click Show next to your Personal API token
3. Copy the token — treat it like a password

App tokens (for production apps installed by other users) require creating an app in the Developer Center and implementing OAuth. For initial development, a personal token is fine.

Workflow

Step 1: Detect Project State

Check the current project:

• Does package.json exist? If not, ask if they want to initialize one (npm init -y)
• Is @mondaydotcomorg/api already installed? If yes, check version and suggest upgrade if < v14
• Is TypeScript configured (tsconfig.json)? This affects which packages to install
• Which package manager? Detect from lockfiles:
  • yarn.lock → use yarn add
  • pnpm-lock.yaml → use pnpm add
  • package-lock.json → use npm install
  • None found → default to npm

Step 2: Install Dependencies

JavaScript projects:

npm install @mondaydotcomorg/api

TypeScript projects:

npm install @mondaydotcomorg/api
npm install -D @mondaydotcomorg/api-types

For full codegen setup (typed query results):

npx @mondaydotcomorg/setup-api

This scaffolds:

• codegen.yml — graphql-codegen config
• graphql.config.yml — IDE extension config
• src/queries.graphql.ts — starter query file
• fetch-schema.sh — script to pull the live schema
• Scripts in package.json: fetch:schema, codegen, fetch:generate

Step 3: Configure Authentication

Create a .env file (if it doesn't exist) and add:

MONDAY_API_TOKEN=your_token_here

Add .env to .gitignore if not already listed.

Node.js does not load .env files automatically. Install dotenv and load it at the entry point of the app:

npm install dotenv

import 'dotenv/config'; // must be first import
import { ApiClient } from '@mondaydotcomorg/api';

Alternatively, with Node 20.6+ you can pass --env-file=.env to the node CLI without any package.

Key points to explain:

• The token mirrors the exact permissions of the user who created it. If the user can't see a board in the UI, API calls can't see it either.
• Do NOT prefix with Bearer — the SDK handles this. For raw HTTP, pass the token directly as the Authorization header value.
• Token regeneration is destructive — regenerating a token instantly invalidates the old one. All integrations using it break.

Step 4: Create SDK Initialization Code

Server-side (Node.js):

Define queries in a .graphql.ts file and import code-generated types (run npm run codegen after npm run fetch:schema):

// src/queries.graphql.ts
export const GET_ME = `
  query GetMe {
    me { name email }
  }
`;

// src/index.ts
import 'dotenv/config';
import { ApiClient } from '@mondaydotcomorg/api';
import { GET_ME } from './queries.graphql';
import type { GetMeQuery } from './generated/graphql';

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

const result = await client.request<GetMeQuery>(GET_ME);
console.log(result.me.name);

Step 5: Pin API Version

Always pin to the current stable version: 2026-01

Explain:

• Versions rotate quarterly: 01, 04, 07, 10
• If you omit the version header, you get the Current version — but when it rotates, your app silently gets the new version which may have breaking changes
• Always pin explicitly — never rely on the default
• Lifecycle: Release Candidate (testing) → Current (stable) → Maintenance (old but works) → Deprecated (may stop working)

Step 6: Verify Setup

Provide a test query and offer to run it live. Use the .graphql.ts pattern:

// src/queries.graphql.ts
export const GET_ME = `
  query GetMe {
    me { name email account { name } }
  }
`;

// src/index.ts
import 'dotenv/config';
import { ApiClient } from '@mondaydotcomorg/api';
import { GET_ME } from './queries.graphql';
import type { GetMeQuery } from './generated/graphql';

const client = new ApiClient({ token: process.env.MONDAY_API_TOKEN! });
const result = await client.request<GetMeQuery>(GET_ME);
console.log('Connected as:', result.me.name);
console.log('Account:', result.me.account.name);

Offer to verify via mcp__monday__all_monday_api:

{ me { name email account { name } } }

If this succeeds, the setup is complete.

Step 7: Suggest Next Steps

• Use /monday-api:build-query to start writing queries
• Use /monday-api:ops for production readiness guidance
• Review the SDK docs: @mondaydotcomorg/api on npm

Key Gotchas

Error Handling