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.

Nested

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)));

At the root

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)));

Querying the main workspace

Every account has a main workspace. Querying the main workspace returns a null workspace ID because you typically cannot return these details via the API.

However, users will eventually be able to query main workspace details via the API as we complete a multi-product migration over the next few months. This capability will be released gradually, so you may not have access yet. All users will have this capability by the end of the migration.

Arguments

You can use the following argument(s) to reduce the number of results returned in your workspaces query.

ArgumentDescription
ids [Int]The specific workspace(s) to return. Please note that this argument's type is [ID!] in API versions 2023-10 and later.
kind WorkspaceKindThe kind of workspaces to return: open or closed.
limit IntThe number of workspaces to return. The default is 25.
order_by WorkspacesOrderByThe order in which to retrieve your workspaces. For now, you can only order by created_at.
page IntThe page number to get. Starts at 1.
state StateThe 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 or fields.

FieldDescriptionSupported arguments
account_product AccountProductThe account product that contains the workspace.
created_at DateThe workspace's creation date.
description StringThe workspace's description.
id IntThe workspace's unique identifier. Please note that this field's type is ID in API versions 2023-10 and later.
kind WorkspaceKindThe 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 WorkspaceSettingsThe workspace's settings.
state StateThe 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.

ArgumentsDescription
description StringThe 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.

ArgumentsDescription
workspace_id Int!The workspace's unique identifier. Please note that this argument's type is ID! in API versions 2023-10 and later.

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.

ArgumentsDescription
kind WorkspaceSubscriberKindThe user's role: subscriber or owner.
user_ids [Int!]The unique identifiers of the users to add to the workspace. Please note that this argument's type is [ID!]! in API versions 2023-10 and later.
workspace_id Int!The workspace's unique identifier. Please note that this argument's type is ID! in API versions 2023-10 and later.

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.

ArgumentsDescription
user_ids [Int]!The unique identifiers of the users to remove from the workspace. Please note that this argument's type is [ID!]! in API versions 2023-10 and later.
workspace_id Int!The workspace's unique identifier. Please note that this argument's type is ID! in API versions 2023-10 and later.

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.

ArgumentsDescription
kind WorkspaceSubscriberTeamThe subscriber's role: subscriber or owner.
team_ids [Int!]The unique identifiers of the teams to add to the workspace. Please note that this argument's type is [ID!]! in API versions 2023-10 and later.
workspace_id Int!The workspace's unique identifier. Please note that this argument's type is ID! in API versions 2023-10 and later.

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.

ArgumentsDescription
team_ids [Int]!The unique identifiers of the teams to remove from the workspace. Please note that this argument's type is [ID!]! in API versions 2023-10 and later.
workspace_id Int!The workspace's unique identifier. Please note that this argument's type is ID! in API versions 2023-10 and later.

📘

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! 😎