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.

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, but you typically can't query its details via the API.

However, users will eventually be able to query main workspace details 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.

Here's the expected behavior for both pre-and post-migration:

Pre-migration

If you query the workspaces on your account, the main workspace will not appear in the results because it has a null or -1 ID. You can, however, filter for boards in the main workspace by passing null as the workspace_id.

query {
  boards (workspace_ids: [null], limit:50) {
    name
  }
}

Post-migration

If you query the workspaces on your account, the main workspace will appear in the results with a real id. You can then use that ID to query the main workspace.

Arguments

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

Argument	Description	Enum values
ids `[ID!]`	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. The default is active.	`active`, `all`, `archived`, `deleted`

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.

Field	Description	Enum values	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 `ID`	The workspace's unique identifier.
is_default_workspace `Boolean`	Returns `true` if a workspace is the default workspace of the product or account. Not all accounts can query the main workspace (see more here).
kind `WorkspaceKind`	The workspace's kind: open or closed.	`closed`, `open`
name `String!`	The workspace's name.
owners_subscribers `[User]`	The workspace's owners. The default is 25. Requires `users:read` scope.		limit `Int` page `Int`
settings `WorkspaceSettings`	The workspace's settings.
state `State`	The state of the workspace. The default is active.	`active`, `all`, `archived`, `deleted`
team_owners_subscribers `[Team!]`	The workspace's team owners. The default is 25. Requires `teams:read` scope.		limit `Int` page `Int`
teams_subscribers `[Team]`	The teams subscribed to the workspace. The default is 25. Requires `teams:read` scope.		limit `Int` page `Int`
users_subscribers `[User]`	The users subscribed to the workspace. The default is 25. 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.

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	Enum values
description `String`	The new workspace's description.
kind `WorkspaceKind!`	The new workspace's kind.	`closed`, `open`
name `String!`	The new workspace's name.

Update a workspace

The update_workspace mutation allows you to update a workspace via the API. You can also specify what fields to query back from the deleted workspace when you run the mutation.

mutation {
  update_workspace (id: 1234567, attributes:{name:"Marketing team", description: "This workspace is for the marketing team." }) {
    id
  }
}

let query = 'mutation { update_workspace (id: 1234567, attributes:{name: \"Marketing team\", description: \"This workspace is for the marketing team.\"}) { 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 what to update.

Arguments	Description
attributes `UpdateWorkspaceAttributesInput!`	The workspace's attributes to update.
id `ID`	The unique identifier of the workspace.

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 `ID!`	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	Enum values
kind `WorkspaceSubscriberKind`	The user's role.	`owner`, `subscriber`
user_ids `[ID!]!`	The unique identifiers of the users to add to the workspace.
workspace_id `ID!`	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 `[ID!]!`	The unique identifiers of the users to remove from the workspace.
workspace_id `ID!`	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	Enum values
kind `WorkspaceSubscriberTeam`	The subscriber's role.	`owner`, `subscriber`
team_ids `[ID!]!`	The unique identifiers of the teams to add to the workspace.
workspace_id `ID!`	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 `[ID!]!`	The unique identifiers of the teams to remove from the workspace.
workspace_id `ID!`	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! 😎

Queries

Querying the main workspace

Pre-migration

Post-migration

Arguments

Fields

Mutations

Create a workspace

Arguments

Update a workspace

Arguments

Delete a workspace

Arguments

Add users to a workspace

Arguments

Delete users from a workspace

Arguments

Add teams to a workspace

Arguments

Delete teams from a workspace

Arguments

📘Join our developer community!

📘
Join our developer community!