Workspaces
monday.com workspaces are used by teams to manage their accounts by departments, teams, or projects. Workspaces can contain boards, dashboards, and folders to help you stay organized.
As a developer working with monday.com, it is important to familiarize yourself with the workspaces
API so you know how to access workspace data. This document will walk you through the available queries and mutations to read and modify the workspaces
object via the API.
Queries
Required scope: workspaces:read
Querying workspaces
will return metadata about one or a collection of workspaces. This method accepts various arguments and returns an array.
You can query workspaces
directly at the root or nest it within a boards
query to return the workspace ID. If you nest it, you only need the boards:read
scope.
query {
boards {
id
workspace_id
}
}
let query = 'query { boards { id workspace_id }}';
fetch ("https://api.monday.com/v2", {
method: 'post',
headers: {
'Content-Type': 'application/json',
'Authorization' : 'YOUR_API_KEY_HERE'
},
body: JSON.stringify({
'query' : query
})
})
.then(res => res.json())
.then(res => console.log(JSON.stringify(res, null, 2)));
Please note that every account has a Main workspace that returns a null
workspace ID because you cannot return Main workspace details via the API.
query {
workspaces (ids: 1234567) {
id
name
kind
description
}
}
let query = 'query { workspaces (id: 1234567) { id name kind description }}}';
fetch ("https://api.monday.com/v2", {
method: 'post',
headers: {
'Content-Type': 'application/json',
'Authorization' : 'YOUR_API_KEY_HERE'
},
body: JSON.stringify({
'query' : query
})
})
.then(res => res.json())
.then(res => console.log(JSON.stringify(res, null, 2)));
Arguments
You can use the following argument(s) to reduce the number of results returned in your workspaces
query.
Argument | Description |
---|---|
ids [Int] | The specific workspace(s) to return. |
kind WorkspaceKind | The kind of workspaces to return: open or closed. |
limit Int | The number of workspaces to return. The default is 25. |
order_by WorkspacesOrderBy | The order in which to retrieve your workspaces. For now, you can only order by created_at. |
page Int | The page number to get. Starts at 1. |
state State | The state of workspaces you want to search by: all, active, archived, or deleted. The default is active. |
Fields
You can use the following field(s) to specify what information your workspaces
query will return. Please note that some fields will have their own arguments.
Field | Description | Supported arguments |
---|---|---|
account_product AccountProduct | The account product that contains the workspace. | |
created_at Date | The workspace's creation date. | |
description String | The workspace's description. | |
id Int | The workspace's unique identifier. | |
kind WorkspaceKind | The workspace's kind: open or closed. | |
name String! | The workspace's name. | |
owners_subscribers [User] | The workspace's owners. The default is 25. Please note: Requires users:read scope. | limit Int page Int |
settings WorkspaceSettings | The workspace's settings. | |
state State | The state of the workspace: all, active, archived, or deleted. The default is active. | |
teams_subscribers [Team] | The teams subscribed to the workspace. The default is 25. Please note: Requires teams:read scope. | limit Int page Int |
users_subscribers [User] | The users subscribed to the workspace. The default is 25. Please note: Requires users:read scope. | limit Int page Int |
Mutations
Required scope: workspaces:write
Create a workspace
The create_workspace
mutation allows you to create a new workspace via the API. You can also specify what fields to query back from the new workspace when you run the mutation. Check out this mutation in action in our Postman library or follow along with these code samples!
mutation {
create_workspace (name:"New Cool Workspace", kind: open, description: "This is a cool description") {
id
description
}
}
let query = 'mutation { create_workspace (name: \"New Cool Workspace\", kind: open, description: \"This is a cool description\") { id description } }';
fetch ("https://api.monday.com/v2", {
method: 'post',
headers: {
'Content-Type': 'application/json',
'Authorization' : 'YOUR_API_KEY_HERE'
},
body: JSON.stringify({
'query' : query
})
})
.then(res => res.json())
.then(res => console.log(JSON.stringify(res, null, 2)));
Arguments
You can use the following argument(s) to define the new workspace's characteristics.
Arguments | Description |
---|---|
description String | The new workspace's description. |
kind WorkspaceKind! | The new workspace's kind: open or closed. |
name String! | The new workspace's name. |
Delete a workspace
The delete_workspace
mutation allows you to delete a workspace via the API. You can also specify what fields to query back from the deleted workspace when you run the mutation.
mutation {
delete_workspace (workspace_id: 1234567) {
id
}
}
let query = 'mutation { delete_workspace (workspace_id: 1234567) { id } }';
fetch ("https://api.monday.com/v2", {
method: 'post',
headers: {
'Content-Type': 'application/json',
'Authorization' : 'YOUR_API_KEY_HERE'
},
body: JSON.stringify({
'query' : query
})
})
.then(res => res.json())
.then(res => console.log(JSON.stringify(res, null, 2)));
Arguments
You can use the following argument(s) to specify which workspace to delete.
Arguments | Description |
---|---|
workspace_id Int! | The workspace's unique identifier. |
Add users to a workspace
The add_users_to_workspace
mutation allows you to add users to a workspace via the API. You can also specify what fields to query back when you run the mutation.
mutation {
add_users_to_workspace (workspace_id: 1234567, user_ids: [12345678, 87654321, 01234567], kind: subscriber) {
id
}
}
let query = 'mutation { add_users_to_workspace (workspace_id: 1234567, user_ids: [12345678, 87654321, 01234567], kind: subscriber) { id } }';
fetch ("https://api.monday.com/v2", {
method: 'post',
headers: {
'Content-Type': 'application/json',
'Authorization' : 'YOUR_API_KEY_HERE'
},
body: JSON.stringify({
'query' : query
})
})
.then(res => res.json())
.then(res => console.log(JSON.stringify(res, null, 2)));
Arguments
You can use the following argument(s) to specify which users to add to the workspace and their subscription type.
Arguments | Description |
---|---|
kind WorkspaceSubscriberKind | The kind of subscribers: subscriber or owner. |
user_ids [Int!] | The unique identifiers of the users to add to the workspace. |
workspace_id Int! | The workspace's unique identifier. |
Delete users from a workspace
The delete_users_from_workspace
mutation allows you to delete users from a workspace via the API. You can also specify what fields to query back when you run the mutation.
mutation {
delete_users_from_workspace (workspace_id: 1234567, user_ids: [12345678, 87654321, 01234567]) {
id
}
}
let query = 'mutation { delete_users_from_workspace (workspace_id: 1234567, user_ids: [12345678, 87654321, 01234567]) { id } }';
fetch ("https://api.monday.com/v2", {
method: 'post',
headers: {
'Content-Type': 'application/json',
'Authorization' : 'YOUR_API_KEY_HERE'
},
body: JSON.stringify({
'query' : query
})
})
.then(res => res.json())
.then(res => console.log(JSON.stringify(res, null, 2)));
Arguments
You can use the following argument(s) to specify which users to remove from the workspace.
Arguments | Description |
---|---|
user_ids [Int]! | The unique identifiers of the users to remove from the workspace. |
workspace_id Int! | The workspace's unique identifier. |
Add teams to a workspace
The add_teams_to_workspace
mutation allows you to add teams to a workspace via the API. You can also specify what fields to query back when you run the mutation.
mutation {
add_teams_to_workspace (workspace_id: 1234567, team_ids: [12345678, 87654321, 01234567]) {
id
}
}
let query = 'mutation { add_teams_to_workspace (workspace_id: 1234567, team_ids: [12345678, 87654321, 01234567]) { id } }';
fetch ("https://api.monday.com/v2", {
method: 'post',
headers: {
'Content-Type': 'application/json',
'Authorization' : 'YOUR_API_KEY_HERE'
},
body: JSON.stringify({
'query' : query
})
})
.then(res => res.json())
.then(res => console.log(JSON.stringify(res, null, 2)));
Arguments
You can use the following argument(s) to specify which teams to add to the workspace.
Arguments | Description |
---|---|
kind WorkspaceSubscriberTeam | The kind of subscribers: subscriber or owner. |
team_ids [Int!] | The unique identifiers of the teams to add to the workspace. |
workspace_id Int! | The workspace's unique identifier. |
Delete teams from a workspace
The delete_teams_from_workspace
mutation allows you to delete teams from a workspace via the API. You can also specify what fields to query back when you run the mutation.
mutation {
delete_teams_from_workspace (workspace_id: 1234567, team_ids: [12345678, 87654321, 01234567]) {
id
}
}
let query = 'mutation { delete_teams_from_workspace (workspace_id: 1234567, team_ids: [12345678, 87654321, 01234567]) { id } }';
fetch ("https://api.monday.com/v2", {
method: 'post',
headers: {
'Content-Type': 'application/json',
'Authorization' : 'YOUR_API_KEY_HERE'
},
body: JSON.stringify({
'query' : query
})
})
.then(res => res.json())
.then(res => console.log(JSON.stringify(res, null, 2)));
Arguments
You can use the following argument(s) to specify which teams to remove from the workspace.
Arguments | Description |
---|---|
team_ids [Int]! | The unique identifiers of the teams to remove from the workspace. |
workspace_id Int! | The workspace's unique identifier. |
Join our developer community!
We've created a community specifically for our devs where you can search through previous topics to find solutions, ask new questions, hear about new features and updates, and learn tips and tricks from other devs. Come join in on the fun! 😎
Updated about 1 month ago