GraphQL Integration via REST API - Complete Documentation
Overview
This action allows you to execute custom GraphQL queries and mutations through Monday.com's REST API endpoint. GraphQL provides a flexible way to request exactly the data you need.Sample Action Level Configurations
Application : Monday.com
Application : Shopify V2
Application : Google Ads
API Configuration
Basic Setup
- HTTP Method: POST
- Endpoint: E.g. https://api.monday.com/v2
- Content-Type: application/json
- Authentication: Bearer token in headers
Request Body Format
{"query": "{{query}}",
"variables": {{variables}}
}
Important:
- {{query}} - Dynamic placeholder for your GraphQL query string
- {{variables}} - Dynamic placeholder for your variables object (raw JSON, not stringified)
Dynamic Value Passing
In Monday.com Integration
When setting up the action, configure the Request Body as:{
"query": "{{query}}",
"variables": {{variables}}
}
Then map the parameters:
- query → Map to a text column or formula that contains your GraphQL query
- variables → Map to a JSON column or formula that contains your variables object
Example Variable Mapping
If you have columns like:- boardId: "123456789"
- itemName: "New Task"
{
"boardId": "123456789",
"itemName": "New Task"
}
cURL Examples
Example 1: Simple Query (No Variables)
curl --location 'https://api.monday.com/v2' \--header 'Content-Type: application/json' \
--header 'Authorization: YOUR_API_TOKEN' \
--data '{
"query": "query { boards(limit: 5) { id name description state } }"
}'
Example 2: Query with Variables
curl --location 'https://api.monday.com/v2' \--header 'Content-Type: application/json' \
--header 'Authorization: YOUR_API_TOKEN' \
--data '{
"query": "query GetBoard($boardId: ID!) { boards(ids: [$boardId]) { id name columns { id title type } } }",
"variables": {
"boardId": "123456789"
}
}'
Example 3: Dynamic Query Template
curl --location 'https://api.monday.com/v2' \--header 'Content-Type: application/json' \
--header 'Authorization: YOUR_API_TOKEN' \
--data '{
"query": "'"$QUERY_STRING"'",
"variables": '"$VARIABLES_JSON"'
}'
Using Bash Variables:
QUERY_STRING='query GetBoard($boardId: ID!) { boards(ids: [$boardId]) { id name } }'
VARIABLES_JSON='{"boardId": "123456789"}'
curl --location 'https://api.monday.com/v2' \
--header 'Content-Type: application/json' \
--header 'Authorization: YOUR_API_TOKEN' \
--data "{
\"query\": \"$QUERY_STRING\",
\"variables\": $VARIABLES_JSON
}"
GraphQL Query Examples
Query 1: Fetch Boards
GraphQL Query:query {
boards(limit: 5) {
id
name
description
state
}
}
Request Body:
{
"query": "query { boards(limit: 5) { id name description state } }"
}
cURL:
curl --location 'https://api.monday.com/v2' \
--header 'Content-Type: application/json' \
--header 'Authorization: YOUR_API_TOKEN' \
--data '{"query": "query { boards(limit: 5) { id name description state } }"}'
Query 2: Get Board by ID (With Variables)
GraphQL Query:query GetBoard($boardId: ID!) {
boards(ids: [$boardId]) {
id
name
columns {
id
title
type
}
}
}
Request Body:
{
"query": "query GetBoard($boardId: ID!) { boards(ids: [$boardId]) { id name columns { id title type } } }",
"variables": {
"boardId": "123456789"
}
}
Dynamic Template:
{
"query": "{{query}}",
"variables": {{variables}}
}
Where:
- {{query}} = "query GetBoard($boardId: ID!) { boards(ids: [$boardId]) { id name columns { id title type } } }"
- {{variables}} = {"boardId": "123456789"}
Query 3: Fetch Items from Board
GraphQL Query:query GetItems($boardId: ID!) {
boards(ids: [$boardId]) {
items {
id
name
column_values {
id
text
value
}
}
}
}
Request Body:
{
"query": "query GetItems($boardId: ID!) { boards(ids: [$boardId]) { items { id name column_values { id text value } } } }",
"variables": {
"boardId": "123456789"
}
}
Query 4: Get Specific Item
GraphQL Query:query GetItem($itemId: ID!) {
items(ids: [$itemId]) {
id
name
state
column_values {
id
title
text
value
}
}
}
Request Body:
{
"query": "query GetItem($itemId: ID!) { items(ids: [$itemId]) { id name state column_values { id title text value } } }",
"variables": {
"itemId": "987654321"
}
}
GraphQL Mutation Examples
Mutation 1: Create Item
GraphQL Mutation:mutation CreateItem($boardId: ID!, $itemName: String!) {
create_item(board_id: $boardId, item_name: $itemName) {
id
name
}
}
Request Body:
{
"query": "mutation CreateItem($boardId: ID!, $itemName: String!) { create_item(board_id: $boardId, item_name: $itemName) { id name } }",
"variables": {
"boardId": "123456789",
"itemName": "New Task"
}
}
cURL:
curl --location 'https://api.monday.com/v2' \
--header 'Content-Type: application/json' \
--header 'Authorization: YOUR_API_TOKEN' \
--data '{
"query": "mutation CreateItem($boardId: ID!, $itemName: String!) { create_item(board_id: $boardId, item_name: $itemName) { id name } }",
"variables": {
"boardId": "123456789",
"itemName": "New Task"
}
}'
Mutation 2: Update Column Value
GraphQL Mutation:mutation UpdateColumn($boardId: ID!, $itemId: ID!, $columnId: String!, $value: JSON!) {
change_column_value(
board_id: $boardId,
item_id: $itemId,
column_id: $columnId,
value: $value
) {
id
name
}
}
Request Body:
{
"query": "mutation UpdateColumn($boardId: ID!, $itemId: ID!, $columnId: String!, $value: JSON!) { change_column_value(board_id: $boardId, item_id: $itemId, column_id: $columnId, value: $value) { id name } }",
"variables": {
"boardId": "123456789",
"itemId": "987654321",
"columnId": "status",
"value": "{\"label\": \"Done\"}"
}
}
Note: The value parameter must be a JSON string (stringified JSON).
Mutation 3: Create Item with Column Values
GraphQL Mutation:mutation CreateItemWithValues($boardId: ID!, $itemName: String!, $columnValues: JSON!) {
create_item(
board_id: $boardId,
item_name: $itemName,
column_values: $columnValues
) {
id
name
}
}
Request Body:
{
"query": "mutation CreateItemWithValues($boardId: ID!, $itemName: String!, $columnValues: JSON!) { create_item(board_id: $boardId, item_name: $itemName, column_values: $columnValues) { id name } }",
"variables": {
"boardId": "123456789",
"itemName": "New Task",
"columnValues": "{\"status\": {\"label\": \"Working on it\"}, \"text\": \"Task description\"}"
}
}
Mutation 4: Delete Item
GraphQL Mutation:mutation DeleteItem($itemId: ID!) {
delete_item(item_id: $itemId) {
id
}
}
Request Body:
{
"query": "mutation DeleteItem($itemId: ID!) { delete_item(item_id: $itemId) { id } }",
"variables": {
"itemId": "987654321"
}
}
Dynamic Value Examples
Example 1: Using Formula Columns
If you have columns:- board_id_column: "123456789"
- item_name_column: "My New Task"
"mutation CreateItem($boardId: ID!, $itemName: String!) { create_item(board_id: $boardId, item_name: $itemName) { id name } }"
Variables Formula:
CONCAT("{\"boardId\": \"", {board_id_column}, "\", \"itemName\": \"", {item_name_column}, "\"}")
Result in Request Body:
{
"query": "{{query}}",
"variables": {{variables}}
}
Becomes:
{
"query": "mutation CreateItem($boardId: ID!, $itemName: String!) { create_item(board_id: $boardId, item_name: $itemName) { id name } }",
"variables": {
"boardId": "123456789",
"itemName": "My New Task"
}
}
Example 2: Multiple Variables
Columns:- board_id: "123456789"
- item_id: "987654321"
- column_id: "status"
- column_value: "Done"
{
"boardId": "{{board_id}}",
"itemId": "{{item_id}}",
"columnId": "{{column_id}}",
"value": "{\"label\": \"{{column_value}}\"}"
}
Response Format
All GraphQL responses follow this structure:Success Response:
{
"data": {
"boards": [
{
"id": "123456789",
"name": "My Board"
}
]
},
"account_id": 123456
}
Error Response:
{
"errors": [
{
"message": "Field 'invalid_field' doesn't exist on type 'Board'",
"locations": [{"line": 1, "column": 20}]
}
],
"account_id": 123456
}
Common Variable Types
| Variable Type | GraphQL Type | Example Value |
|---|---|---|
| Board ID | ID! | "123456789" |
| Item ID | ID! | "987654321" |
| Column ID | String! | "status" |
| Item Name | String! | "New Task" |
| Column Values | JSON! | "{\"label\": \"Done\"}" |
| Integer | Int | 10 |
| Boolean | Boolean | true |
| Array of IDs | [ID!] | ["123", "456"] |
Testing Your Setup
Test Query
curl --location 'https://api.monday.com/v2' \--header 'Content-Type: application/json' \
--header 'Authorization: YOUR_API_TOKEN' \
--data '{
"query": "query { me { id name email } }"
}'
Expected Response:
{
"data": {
"me": {
"id": "12345",
"name": "Your Name",
"email": "[email protected]"
}
}
}
Best Practices
- Always Use Variables: Don't concatenate values directly into query strings
Good: "query": "mutation($boardId: ID!) {...}", "variables": {"boardId": "123"}
Bad: "query": "mutation { create_item(board_id: 123) {...} }"
- Escape JSON in Column Values: When setting column values, JSON must be stringified
"value": "{\"label\": \"Done\"}"
- Type Definitions: Always specify types for variables
- $boardId: ID! (required)
- $itemName: String (optional)
- Test in GraphQL Playground: Use Monday.com's API playground before implementing
- Error Handling: Always check for errors array in response
Troubleshooting
Issue: "Field doesn't exist"
- Check spelling of field names
- Verify field is available in your Monday.com plan
- Check GraphQL schema documentation
Issue: "Variable type mismatch"
- Ensure variable types match query definition
- Check if value should be stringified JSON
Issue: "Authentication failed"
- Verify API token is valid
- Check token has required permissions
- Ensure token is prefixed in header
Issue: "Parse error"
- Validate JSON syntax
- Check for unescaped quotes in query string
- Ensure variables is valid JSON object
Additional Resources
- Monday.com API Documentation: https://developer.monday.com/api-reference/docs
- GraphQL Documentation: https://graphql.org/learn/
- API Playground: https://monday.com/developers/v2/try-it-yourself
Support
For issues or questions:- Check Monday.com Developer Forum
- Review API documentation
- Contact Monday.com support with:
- Request body
- Response received
- Error messages
Last edited:
