Apps Framework DocsCommunityAPI Playground

Workspaces

Suggest Edits

monday.com workspaces are used by teams to organize and manage their accounts by departments, teams, or projects. Workspaces can contain boards, dashboards, and folders.

Workspaces queries

Required scope: workspaces:read

You can use workspaces at the root of your query or nest the field within a boards query.

Note: Every account will have a workspace called the Main Workspace by default that has a null workspace ID. You cannot return the Main Workspace details via the API.

query {
  workspaces (ids: 20178755) {
    id
    name
    kind
    description
    }
  }
}

fetch ("https://api.monday.com/v2", {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
    'Authorization' : 'YourSuperSecretAPIkey'
   },
   body: JSON.stringify({
     query : "query { boards { workspace { id name kind description }}}"
   })
  })

If you only need the ID of a workspace, you only need the boards:read scope.

query {
  boards {
    id
    workspace_id
  }
}

fetch ("https://api.monday.com/v2", {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
    'Authorization' : 'YourSuperSecretAPIkey'
   },
   body: JSON.stringify({
     query : "query { boards { id workspace_id }}"
   })
  })

curl --location --request POST 'https://api.monday.com/v2' \
--header 'Authorization: YourSuperSecretAPIkey' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"query { boards { id workspace_id }}"}'

Arguments

The following workspaces arguments can reduce the number of workspaces returned.

ArgumentDescription
ids [Int]The workspace's identifier.
kind WorkspaceKindThe workspace's kind: open or closed.
limit IntThe number of items returned. The default is 25.
state StateThe state of the workspace: all, active, archived, or deleted. The default is active.
order_by WorkspacesOrderByThe order in which to retrieve your boards. For now, you can only order by created_at.
page IntThe page number to get, starting at 1.

Fields

Fields are used to return specific properties in an object. The following fields will determine what information is returned from your workspaces query.

FieldDescriptionSupported arguments
account_product AccountProductThe account product that contains the workspace.
created_at DateThe workspace's creation date.
description StringThe workspace's description.
id Int!The workspace's unique identifier.
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

Workspaces mutations

Required scope: workspaces:write

Create a workspace

Allows you to create a new workspace. After the mutation runs, you can create boards in it as shown in the creating boards section.

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' : 'YourSuperSecretAPIkey'
   },
   body: JSON.stringify({
     query : "mutation { create_workspace (name: \"New Cool Workspace\", kind: open, description: \"This is a cool description\") { id description } }"
   })
  })

You can find the Postman request to create a workspace here.

Arguments for create a workspace

The following arguments define the new workspace's characteristics.

ArgumentsDescription
name String!The new workspace's name.
kind WorkspaceKind!The new workspace's kind: open or closed.
description StringThe new workspace's description.

Delete a workspace

Allows you to delete a workspace. 

mutation {
  delete_workspace (workspace_id: 12345678) {
    id
  }
}

fetch ("https://api.monday.com/v2", {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
    'Authorization' : 'YourSuperSecretAPIkey'
   },
   body: JSON.stringify({
     query : "mutation { delete_workspace (workspace_id: 12345678) { id } }"
   })
  })

Arguments for delete a workspace

The following argument specifies which workspace to delete.

ArgumentsDescription
workspace_id Int!The workspace's unique identifier.

Add users to a workspace

Allows you to add users to a workspace. You can define if users will be added as regular subscribers or as owners of the workspace.

mutation {
    add_users_to_workspace (workspace_id: 12345678, user_ids: [123456, 654321, 012345], kind: subscriber) {
        id
    }
}

fetch ("https://api.monday.com/v2", {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
    'Authorization' : 'YourSuperSecretAPIkey'
   },
   body: JSON.stringify({
     query : "mutation { add_users_to_workspace (workspace_id: 12345678, user_ids: [123456, 654321, 012345], kind: subscriber) { id } }"
   })
  })

Arguments for add users to a workspace

The following arguments define which users to add to the workspace and their subscription type.

ArgumentsDescription
workspace_id Int!The workspace's unique identifier.
user_ids [Int!]User IDs to add to the workspace.
kind WorkspaceSubscriberKindKind of subscribers added: subscriber or owner.

Delete users from a workspace

Allows you to delete users from a workspace.

mutation {
    delete_users_from_workspace (workspace_id: 12345678, user_ids: [123456, 654321, 012345]) {
        id
    }
}

fetch ("https://api.monday.com/v2", {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
    'Authorization' : 'YourSuperSecretAPIkey'
   },
   body: JSON.stringify({
     query : "mutation { delete_users_from_workspace (workspace_id: 12345678, user_ids: [123456, 654321, 012345]) { id } }"
   })
  })

Arguments for delete users from a workspace

The following arguments define which users to remove from the workspace.

ArgumentsDescription
workspace_id Int!The workspace's unique identifier.
user_ids [Int!]User IDs to delete from the workspace.

Add teams to a workspace

Allows you to add teams to a workspace.

mutation {
    add_teams_to_workspace (workspace_id: 12345678, team_ids: [123456, 654321, 012345]) {
        id
    }
}

fetch ("https://api.monday.com/v2", {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
    'Authorization' : 'YourSuperSecretAPIkey'
   },
   body: JSON.stringify({
     query : "mutation { add_teams_to_workspace (workspace_id: 12345678, team_ids: [123456, 654321, 012345]) { id } }"
   })
  })

Arguments for add teams to a workspace

The following arguments define which teams to add to the workspace.

ArgumentsDescription
workspace_id Int!The workspace's unique identifier.
team_ids [Int!]Team IDs to add to the workspace.

Delete teams from a workspace

Allows you to delete teams from a workspace.

mutation {
    delete_teams_from_workspace (workspace_id: 12345678, team_ids: [123456, 654321, 012345]) {
        id
    }
}

fetch ("https://api.monday.com/v2", {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
    'Authorization' : 'YourSuperSecretAPIkey'
   },
   body: JSON.stringify({
     query : "mutation { delete_teams_from_workspace (workspace_id: 12345678, team_ids: [123456, 654321, 012345]) { id } }"
   })
  })

Arguments for delete teams from a workspace

The following arguments define which teams to remove from the workspace.

ArgumentsDescription
workspace_id Int!The workspace's unique identifier.
team_ids [Int!]Team IDs to delete from the workspace.

📘

Have questions?

Join our developer community! You can share your questions and learn from fellow users and monday.com product experts.

Don’t forget to search before opening a new topic!

Updated 5 days ago