---
updatedAt: 2026-05-29T17:03:39.000Z
---

# Get workspaces

Returns all workspaces the authenticated user is a member of, whether the workspace or user is active or inactive.

**Authorization scope**: `workspaces:read`


# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "MURAL Public API",
    "description": "MURAL's Public API\n",
    "termsOfService": "https://start.mural.co/developer-beta/terms",
    "contact": {
      "name": "MURAL",
      "email": "m4d@mural.co"
    },
    "version": "1.0.0",
    "x-logo": {
      "url": "https://app.mural.co/static/images/new-logo.svg",
      "href": "https://mural.co"
    }
  },
  "servers": [
    {
      "url": "https://app.mural.co/api/public/{version}",
      "description": "MURAL Public API",
      "variables": {
        "version": {
          "default": "v1",
          "enum": [
            "v1"
          ]
        }
      }
    }
  ],
  "tags": [
    {
      "name": "Workspaces"
    }
  ],
  "paths": {
    "/workspaces": {
      "get": {
        "security": [
          {
            "oauth2": [
              "workspaces:read"
            ]
          }
        ],
        "tags": [
          "Workspaces"
        ],
        "summary": "Get workspaces",
        "description": "Returns all workspaces the authenticated user is a member of, whether the workspace or user is active or inactive.\n\n**Authorization scope**: `workspaces:read`\n",
        "operationId": "getWorkspaces",
        "parameters": [
          {
            "$ref": "#/components/parameters/limit"
          },
          {
            "$ref": "#/components/parameters/nextToken"
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/PaginatedList"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "value": {
                          "description": "Array of workspaces returned.",
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/WorkspaceBrief"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/LimitBadRequest"
                    },
                    {
                      "$ref": "#/components/schemas/PaginationBadRequest"
                    },
                    {
                      "$ref": "#/components/schemas/NextTokenExpired"
                    }
                  ]
                },
                "examples": {
                  "Next Token Expired": {
                    "value": {
                      "code": "NEXT_TOKEN_EXPIRED",
                      "message": "The next token has expired or does not exist."
                    }
                  },
                  "Invalid limit": {
                    "value": {
                      "code": "LIMIT_INVALID",
                      "message": "The limit is invalid."
                    }
                  },
                  "Invalid pagination": {
                    "value": {
                      "code": "PAGINATION_INVALID",
                      "message": "The pagination is invalid."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "oauth2": {
        "type": "oauth2",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://app.mural.co/api/public/v1/authorization/oauth2",
            "tokenUrl": "https://app.mural.co/api/public/v1/authorization/oauth2/token",
            "refreshUrl": "https://app.mural.co/api/public/v1/authorization/oauth2/token",
            "scopes": {
              "rooms:read": "Read information about rooms (for room members and owners).",
              "rooms:write": "Write information about rooms (for room owners).",
              "users:read": "Read information about users (guests, members, and visitors).",
              "workspaces:write": "Write information about workspaces (for workspace owners)",
              "workspaces:read": "Read information about workspaces (for workspace members and owners).",
              "murals:read": "Read information about murals (for mural members and owners).",
              "murals:write": "Write information about murals (for mural members and owners).",
              "identity:read": "Read information about currently authenticated user.",
              "templates:read": "Read information about templates.",
              "templates:write": "Write information about templates (for templates owners)"
            }
          }
        }
      }
    },
    "schemas": {
      "WorkspaceId": {
        "type": "string",
        "description": "ID of a workspace.",
        "minLength": 5,
        "maxLength": 34,
        "example": "workspace1234"
      },
      "Timestamp": {
        "type": "number",
        "description": "Timestamp in milliseconds.",
        "example": 1608060691000
      },
      "BaseError": {
        "description": "Thorough details regarding an error response from the API.",
        "type": "object",
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "description": "Error code",
            "example": "ERROR",
            "type": "string",
            "maxLength": 36
          },
          "message": {
            "description": "Short, human readable, description of the error.",
            "example": "Unknown server error",
            "type": "string"
          }
        }
      },
      "DetailedError": {
        "allOf": [
          {
            "$ref": "#/components/schemas/BaseError"
          },
          {
            "type": "object",
            "properties": {
              "details": {
                "description": "Error details.",
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "code",
                    "message"
                  ],
                  "properties": {
                    "code": {
                      "description": "Error code",
                      "example": "SUB_ERROR",
                      "type": "string",
                      "maxLength": 36
                    },
                    "message": {
                      "description": "Short, human readable, description of the error.",
                      "example": "Unknown server error",
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        ]
      },
      "List": {
        "type": "object",
        "properties": {
          "value": {
            "type": "array",
            "description": "An array of entities.",
            "items": {
              "type": "object"
            }
          }
        }
      },
      "PaginatedList": {
        "allOf": [
          {
            "$ref": "#/components/schemas/List"
          },
          {
            "type": "object",
            "properties": {
              "next": {
                "description": "The token to get the next page of items.",
                "type": "string",
                "example": "eyJmaWx0ZXJCeSI6ImFjdGl2ZSIsImV4cGlyYXRpb24iOjE1MTcxMTAxNDYyMTZ9"
              }
            }
          }
        ]
      },
      "LimitBadRequest": {
        "description": "The request parameter for pagination limit was malformed or has invalid parameters.",
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Request parameter for pagination limit was invalid.",
            "example": "LIMIT_INVALID",
            "enum": [
              "LIMIT_INVALID"
            ]
          },
          "message": {
            "type": "string",
            "description": "Human readable message for limit error.",
            "example": "Request query string for \"limit\" should be less than 100."
          }
        }
      },
      "PaginationBadRequest": {
        "description": "The pagination parameter is not valid.",
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "The requested pagination parameter is not valid.",
            "example": "PAGINATION_INVALID",
            "enum": [
              "PAGINATION_INVALID"
            ]
          },
          "message": {
            "type": "string",
            "description": "Human readable message for pagination error.",
            "example": "The pagination is not valid."
          }
        }
      },
      "NextTokenExpired": {
        "description": "The token supplied to the next parameter has expired.",
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "enum": [
              "NEXT_TOKEN_EXPIRED"
            ],
            "example": "NEXT_TOKEN_EXPIRED"
          },
          "message": {
            "type": "string",
            "example": "The next token has expired or does not exist."
          }
        }
      },
      "CompanyId": {
        "type": "string",
        "description": "ID of a company.",
        "minLength": 1,
        "maxLength": 50,
        "example": "mycompany9876"
      },
      "WorkspaceName": {
        "type": "string",
        "description": "Name of the workspace.",
        "example": "My Company's Q4 goals"
      },
      "WorkspaceSharingSettings": {
        "type": "object",
        "properties": {
          "link": {
            "type": "string",
            "description": "Link that a member with an account can use to access a workspace.\n",
            "format": "uri",
            "example": "https://app.mural.co/invitation/team/asd6544?code=ab6b420951a448eaaa52e83b01144cbe&sender=uf3343eb51571c80392e45271"
          }
        }
      },
      "Datestring": {
        "type": "string",
        "format": "date",
        "example": "2020-01-20"
      },
      "WorkspaceBrief": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/WorkspaceId"
          },
          "name": {
            "$ref": "#/components/schemas/WorkspaceName"
          },
          "description": {
            "type": "string",
            "description": "Description of the workspace.",
            "example": "This workspace is for deciding on Q4 goals for every team in our company"
          },
          "sharingSettings": {
            "$ref": "#/components/schemas/WorkspaceSharingSettings"
          },
          "locked": {
            "type": "boolean",
            "description": "When true, the workspace is locked."
          },
          "suspended": {
            "type": "boolean",
            "description": "When true, the workspace has beeen suspended.",
            "example": false
          },
          "companyId": {
            "allOf": [
              {
                "$ref": "#/components/schemas/CompanyId"
              },
              {
                "description": "Unique ID of the company."
              },
              {
                "example": "mycompany9876"
              }
            ]
          },
          "createdOn": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Timestamp"
              },
              {
                "description": "Timestamp in milliseconds of the workspace creation."
              },
              {
                "example": 1608060691000
              }
            ]
          },
          "trialEnds": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Datestring"
              },
              {
                "description": "Date on which the trial ended. Formatted as YYYY-MM-DD.",
                "example": "2020-03-20"
              }
            ]
          },
          "trialExtended": {
            "type": "boolean",
            "description": "When true, the trial has been extended."
          }
        },
        "required": [
          "id",
          "name",
          "description",
          "sharingSettings",
          "locked",
          "suspended",
          "createdOn"
        ]
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "No authorization",
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/BaseError"
                },
                {
                  "type": "object",
                  "properties": {
                    "code": {
                      "enum": [
                        "UNAUTHORIZED",
                        "TOKEN_EXPIRED"
                      ]
                    }
                  }
                }
              ]
            },
            "examples": {
              "authorization": {
                "summary": "No authorization",
                "value": {
                  "code": "UNAUTHORIZED",
                  "message": "You don't have the required permissions to access this endpoint."
                }
              },
              "expiredToken": {
                "summary": "Expired token",
                "value": {
                  "code": "TOKEN_EXPIRED",
                  "message": "Your token has expired. You need to refresh your OAuth token."
                }
              }
            }
          }
        }
      },
      "ServerError": {
        "description": "API error",
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/DetailedError"
                },
                {
                  "type": "object",
                  "properties": {
                    "code": {
                      "enum": [
                        "INTERNAL_SERVER_ERROR"
                      ],
                      "example": "INTERNAL_SERVER_ERROR"
                    },
                    "message": {
                      "example": "An unexpected condition was encountered that prevented us from fulfilling the request. Try it again later, please."
                    }
                  }
                }
              ]
            }
          }
        }
      }
    },
    "parameters": {
      "limit": {
        "in": "query",
        "name": "limit",
        "schema": {
          "type": "integer"
        },
        "required": false,
        "description": "Maximum number of results to be returned by the endpoint."
      },
      "nextToken": {
        "in": "query",
        "name": "next",
        "schema": {
          "type": "string"
        },
        "required": false,
        "description": "Token to get the next page of items."
      }
    }
  },
  "x-readme": {
    "explorer-enabled": false,
    "proxy-enabled": false
  }
}
```