GraphQL Integration via REST API - Complete Documentation

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"

Your {{variables}} should resolve to:
{
"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"

Query Formula:
"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"

Variables Construction:
{
"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​

---

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​

1. 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) {...} }"
2. Escape JSON in Column Values: When setting column values, JSON must be stringified
   "value": "{\"label\": \"Done\"}"
   
3. Type Definitions: Always specify types for variables
   • $boardId: ID! (required)
   • $itemName: String (optional)
4. Test in GraphQL Playground: Use Monday.com's API playground before implementing
   • URL: https://monday.com/developers/v2/try-it-yourself
5. 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:

1. Check Monday.com Developer Forum
2. Review API documentation
3. Contact Monday.com support with:
   • Request body
   • Response received
   • Error messages