monday.com workspaces are used by teams to manage their accounts by departments, teams, or projects. They contain boards, dashboards, and folders to help you stay organized.

Queries

You can use the workspaces query to retrieve workspace data via the API.

Required scope: workspaces:read
Returns an array containing metadata about one or a collection of workspaces
Can be queried directly at the root or nested within a boards query (returns the workspace ID, only requires the boards:read scope)

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

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 arguments to reduce the number of results returned in your workspaces query.

[block:parameters]

{
  "data": {
    "h-0": "Argument",
    "h-1": "Description",
    "h-2": "Enum Values",
    "0-0": "ids `[ID!]`",
    "0-1": "The specific workspace(s) to return.",
    "0-2": "",
    "1-0": "kind `WorkspaceKind`",
    "1-1": "The kind of workspaces to return: _open_ or _closed_.",
    "1-2": "",
    "2-0": "limit `Int`",
    "2-1": "The number of workspaces to return. The default is 25.",
    "2-2": "",
    "3-0": "order_by `WorkspacesOrderBy`",
    "3-1": "The order in which to retrieve your workspaces. For now, you can only order by _created_at_.",
    "3-2": "",
    "4-0": "page `Int`",
    "4-1": "The page number to get. Starts at 1.",
    "4-2": "",
    "5-0": "state `State`",
    "5-1": "The state of workspaces you want to search by. The default is `active`.",
    "5-2": "`active`  \n`all`  \n`archived`, `deleted`"
  },
  "cols": 3,
  "rows": 6,
  "align": [
    "left",
    "left",
    "left"
  ]
}

[/block]

Fields

You can use the following fields to specify what information your workspaces query will return. Some fields support their own subfields.

[block:parameters]

{
  "data": {
    "h-0": "Field",
    "h-1": "Description",
    "h-2": "Enum Values",
    "h-3": "Supported Subfields",
    "0-0": "account_product [`AccountProduct`](https://developer.monday.com/api-reference/docs/other-types#account-product)",
    "0-1": "The account's product that contains the workspace.",
    "0-2": "",
    "0-3": "",
    "1-0": "created_at `Date`",
    "1-1": "The workspace's creation date.",
    "1-2": "",
    "1-3": "",
    "2-0": "description `String`",
    "2-1": "The workspace's description.",
    "2-2": "",
    "2-3": "",
    "3-0": "id `ID`",
    "3-1": "The workspace's unique identifier.",
    "3-2": "",
    "3-3": "",
    "4-0": "is_default_workspace `Boolean`",
    "4-1": "Whether the workspace is the default workspace of the product or account. Not all accounts can query the _main workspace_ (see more [here](https://developer.monday.com/api-reference/reference/workspaces#querying-the-main-workspace)).",
    "4-2": "",
    "4-3": "",
    "5-0": "kind `WorkspaceKind`",
    "5-1": "The workspace's kind. ",
    "5-2": "`closed` `open`",
    "5-3": "",
    "6-0": "name `String!`",
    "6-1": "The workspace's name.",
    "6-2": "",
    "6-3": "",
    "7-0": "owners_subscribers [`[User]`](https://developer.monday.com/api-reference/docs/users#fields)",
    "7-1": "The workspace's owners. The default is 25. Requires **`users:read`** scope. ",
    "7-2": "",
    "7-3": "",
    "8-0": "settings `WorkspaceSettings`",
    "8-1": "The workspace's settings.",
    "8-2": "",
    "8-3": "icon `WorkspaceIcon`",
    "9-0": "state `State`",
    "9-1": "The state of the workspace. The default is `active`.",
    "9-2": "`active`  \n`all` `archived`  \n`deleted`",
    "9-3": "",
    "10-0": "team_owners_subscribers [`[Team!]`](https://developer.monday.com/api-reference/docs/teams#fields)",
    "10-1": "The workspace's team owners. The default is 25. Requires **`teams:read`** scope.",
    "10-2": "",
    "10-3": "",
    "11-0": "teams_subscribers [`[Team]`](https://developer.monday.com/api-reference/docs/teams#fields)",
    "11-1": "The teams subscribed to the workspace. The default is 25. Requires **`teams:read`** scope.",
    "11-2": "",
    "11-3": "",
    "12-0": "users_subscribers [`[User]`](https://developer.monday.com/api-reference/docs/users#fields)",
    "12-1": "The users subscribed to the workspace. The default is 25. Requires **`users:read`** scope.",
    "12-2": "",
    "12-3": ""
  },
  "cols": 4,
  "rows": 13,
  "align": [
    "left",
    "left",
    "left",
    "left"
  ]
}

[/block]

Mutations

The API allows you to create, update, and delete workspaces using the following mutations. These operations let you programmatically control a workspace's full lifecycle.

Create workspace

Required scope: workspaces:write

The create_workspace mutation creates a new workspace via the API. You can specify which fields to return in the mutation response.

mutation {
  create_workspace(
    name:"New Cool Workspace"
    kind: open
    description: "This is a cool description"
    account_product_id: 505616
	) {
    id
    description
  }
}

Arguments

You can use the following arguments to define the new workspace's characteristics.

Arguments	Description	Enum Values
account_product_id `ID`	The unique identifier of the account’s product in which to create the new workspace.
description `String`	The new workspace's description.
kind `WorkspaceKind!`	The new workspace's kind.	`closed` `open`
name `String!`	The new workspace's name.

Update workspace

Required scope: workspaces:write

The update_workspace mutation updates a workspace via the API. You can specify which fields to return in the mutation response.

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

Arguments

You can use the following arguments to specify which workspace to update.

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

Add teams to workspace

Required scope: workspaces:write

The add_teams_to_workspace mutation adds teams to a workspace via the API. You can specify which fields to return in the mutation response.

mutation {
  add_teams_to_workspace(
    workspace_id: 1234567
    team_ids: [
      12345678
      87654321
      56789012
    ]
	) {
    id
  }
}

Arguments

You can use the following arguments to specify which teams to add to the workspace and their subscription type.

[block:parameters]

{
  "data": {
    "h-0": "Arguments",
    "h-1": "Description",
    "h-2": "Enum Values",
    "0-0": "kind `WorkspaceSubscriberTeam`",
    "0-1": "The subscriber's role.",
    "0-2": "`owner`  \n`subscriber`",
    "1-0": "team_ids `[ID!]!`",
    "1-1": "The teams' unique identifiers. ",
    "1-2": "",
    "2-0": "workspace_id `ID!`",
    "2-1": "The workspace's unique identifier.",
    "2-2": ""
  },
  "cols": 3,
  "rows": 3,
  "align": [
    "left",
    "left",
    "left"
  ]
}

[/block]

Add users to workspace

Required scope: workspaces:write

The add_users_to_workspace mutation adds users to a workspace via the API. You can specify which fields to return in the mutation response.

mutation {
  add_users_to_workspace(
    workspace_id: 1234567
    user_ids: [
      12345678
      87654321
      56789012
    ]
    kind: subscriber
	) {
    id
  }
}

Arguments

You can use the following arguments to specify which users to add to the workspace and their subscription type.

[block:parameters]

{
  "data": {
    "h-0": "Arguments",
    "h-1": "Description",
    "h-2": "Enum Values",
    "0-0": "kind `WorkspaceSubscriberKind`",
    "0-1": "The user's role.",
    "0-2": "`owner`  \n`subscriber`",
    "1-0": "user_ids `[ID!]!`",
    "1-1": "The users' unique identifiers. ",
    "1-2": "",
    "2-0": "workspace_id `ID!`",
    "2-1": "The workspace's unique identifier.",
    "2-2": ""
  },
  "cols": 3,
  "rows": 3,
  "align": [
    "left",
    "left",
    "left"
  ]
}

[/block]

Delete workspace

Required scope: workspaces:write

The delete_workspace mutation deletes a workspace via the API. You can specify which fields to return in the mutation response.

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

Arguments

You can use the following argument to specify which workspace to delete.

Arguments	Description
workspace_id `ID!`	The workspace's unique identifier.

Delete teams from workspace

Required scope: workspaces:write

The delete_teams_from_workspace mutation deletes teams from a workspace via the API. You can specify which fields to return in the mutation response.

mutation {
  delete_teams_from_workspace(
    workspace_id: 1234567
    team_ids: [
      12345678
      87654321
      56789012
    ]
	) {
    id
  }
}

Arguments

You can use the following arguments to specify which teams to delete from the workspace.

Arguments	Description
team_ids `[ID!]!`	The teams' unique identifiers.
workspace_id `ID!`	The workspace's unique identifier.

Delete users from workspace

Required scope: workspaces:write

The delete_users_from_workspace mutation deletes users from a workspace via the API. You can specify which fields to return in the mutation response.

mutation {
  delete_users_from_workspace(
    workspace_id: 1234567
    user_ids: [
      12345678
      87654321
      56789012
    ]
	) {
    id
  }
}

Arguments

You can use the following arguments to specify which users to delete from the workspace.

Arguments	Description
user_ids `[ID!]!`	The users' unique identifiers.
workspace_id `ID!`	The workspace's unique identifier.