{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/google-chat-integrations-for-workspace/json-schema/google-chat-integrations-for-workspace-set-up-space-request-schema.json",
  "title": "SetUpSpaceRequest",
  "description": "Request to create a space and add specified users to it.",
  "x-generated": "2026-11-11",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/google-chat-integrations-for-workspace-spaces-api-openapi.yml#/components/schemas/SetUpSpaceRequest",
  "properties": {
    "space": {
      "$ref": "#/$defs/Space",
      "description": "Required. The `Space.spaceType` field is required. To create a space, set `Space.spaceType` to `SPACE` and set `Space.displayName`. If you receive the error message `ALREADY_EXISTS` when setting up a space, try a different `displayName`. An existing space within the Google Workspace organization might already use this display name. To create a group chat, set `Space.spaceType` to `GROUP_CHAT`. Don't set `Space.displayName`. To create a 1:1 conversation between humans, set `Space.spaceType` to `DIRECT_MESSAGE` and set `Space.singleUserBotDm` to `false`. Don't set `Space.displayName` or `Space.spaceDetails`. To create an 1:1 conversation between a human and the calling Chat app, set `Space.spaceType` to `DIRECT_MESSAGE` and `Space.singleUserBotDm` to `true`. Don't set `Space.displayName` or `Space.spaceDetails`. If a `DIRECT_MESSAGE` space already exists, that space is returned instead of creating a new space."
    },
    "requestId": {
      "description": "Optional. A unique ID for this request. A random UUID is recommended. Specifying a request ID makes the request idempotent, which ensures that multiple identical requests with the same request ID result in only a single space being created. Subsequent requests with the same request ID return the existing space and do not update the space, even if the requested details differ from the current state. To use this field effectively: - Ensure that subsequent requests are identical and use the same authentication credentials as the original request. - If a space was already created with the provided request ID, the request returns that space. Note that the returned space might not be fully populated; the API echoes the space in your request with the system-assigned resource name populated. To retrieve the latest metadata for the space, call `GetSpace`. - Reusing an existing request ID with a different authenticated user results in an error.",
      "type": "string"
    },
    "memberships": {
      "description": "Optional. The Google Chat users or groups to invite to join the space. Omit the calling user, as they are added automatically. The set currently allows up to 49 memberships (in addition to the caller). For human membership, the `Membership.member` field must contain a `user` with `name` populated (format: `users/{user}`) and `type` set to `User.Type.HUMAN`. You can only add human users when setting up a space (adding Chat apps is only supported for direct message setup with the calling app). You can also add members using the user's email as an alias for {user}. For example, the `user.name` can be `users/example@gmail.com`. To invite Gmail users or users from external Google Workspace domains, user's email must be used for `{user}`. For Google group membership, the `Membership.group_member` field must contain a `group` with `name` populated (format `groups/{group}`). You can only add Google groups when setting `Space.spaceType` to `SPACE`. Optional when setting `Space.spaceType` to `SPACE`. Required when setting `Space.spaceType` to `GROUP_CHAT`, along with at least two memberships. Required when setting `Space.spaceType` to `DIRECT_MESSAGE` with a human user, along with exactly one membership. Must be empty when creating a 1:1 conversation between a human and the calling Chat app (when setting `Space.spaceType` to `DIRECT_MESSAGE` and `Space.singleUserBotDm` to `true`).",
      "type": "array",
      "items": {
        "$ref": "#/$defs/Membership"
      }
    }
  },
  "type": "object",
  "$defs": {
    "AccessPermissionSetting": {
      "properties": {
        "principals": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Principal"
          },
          "description": "Optional. Unordered list. Allowed principals for this permission."
        }
      },
      "description": "An access permission setting.",
      "type": "object"
    },
    "AccessPermissionSettings": {
      "properties": {
        "viewSpaceMembershipSetting": {
          "$ref": "#/$defs/AccessPermissionSetting",
          "description": "Optional. Access permission setting for viewing space membership. Must be specified together with `PermissionSettings.view_space_membership` in the update mask and request body when updating who can view space membership. When granting view access to a target audience, you must also grant `PermissionSettings.view_space_membership` to all members in the same request. To remove an existing target audience (for example, to restrict view access to space managers or assistant managers only), specify an empty `AccessPermissionSetting` (with no `principals`)."
        },
        "discoverSpaceSetting": {
          "$ref": "#/$defs/AccessPermissionSetting",
          "description": "Optional. Access permission setting for discovering the space."
        },
        "joinSpaceSetting": {
          "$ref": "#/$defs/AccessPermissionSetting",
          "description": "Optional. Access permission setting for joining the space."
        }
      },
      "description": "Access permission settings for a space.",
      "type": "object"
    },
    "AccessSettings": {
      "type": "object",
      "description": "Represents the [access setting](https://support.google.com/chat/answer/11971020) of the space.",
      "properties": {
        "accessPermissionSettings": {
          "$ref": "#/$defs/AccessPermissionSettings",
          "description": "Optional. Access permission settings for the space. To set the target audience when creating a space, specify the `accessSettings.audience` field in your request."
        },
        "audience": {
          "description": "Optional. The resource name of the [target audience](https://support.google.com/a/answer/9934697) who can discover the space, join the space, and preview the messages in the space. If unset, only users or Google Groups who have been individually invited or added to the space can access it. For details, see [Make a space discoverable to a target audience](https://developers.google.com/workspace/chat/space-target-audience). Format: `audiences/{audience}` To use the default target audience for the Google Workspace organization, set to `audiences/default`. Reading the target audience supports: - [User authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user) - [App authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-app) with [administrator approval](https://support.google.com/a?p=chat-app-auth) with the `chat.app.spaces` scope. This field is not populated when using the `chat.bot` scope with [app authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-app). Setting the target audience requires [user authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user).",
          "type": "string"
        },
        "accessState": {
          "enum": [
            "ACCESS_STATE_UNSPECIFIED",
            "PRIVATE",
            "DISCOVERABLE"
          ],
          "readOnly": true,
          "type": "string",
          "description": "Output only. Indicates the access state of the space."
        }
      }
    },
    "Audience": {
      "description": "A target audience in Google Chat. A target audience represents a group of users within a Google Workspace organization, defined by an administrator. Target audiences are used to configure access and visibility settings for resources, such as making a space discoverable to a specific group of users. For more details, see [Target audiences](https://support.google.com/a/answer/9934697) and [Make a space discoverable to a target audience](https://developers.google.com/workspace/chat/space-target-audience).",
      "type": "object",
      "properties": {
        "name": {
          "description": "The resource name of the [target audience](https://support.google.com/a/answer/9934697) who can discover or join the space. For details, see [Make a space discoverable to a target audience](https://developers.google.com/workspace/chat/space-target-audience). Format: `audiences/{audience}` To use the default target audience for the Google Workspace organization, set to `audiences/default`.",
          "type": "string"
        }
      }
    },
    "Group": {
      "description": "A Google Group in Google Chat.",
      "type": "object",
      "properties": {
        "name": {
          "description": "Resource name for a Google Group. Represents a [group](https://cloud.google.com/identity/docs/reference/rest/v1/groups) in Cloud Identity Groups API. Format: groups/{group}",
          "type": "string"
        }
      }
    },
    "Membership": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Identifier. Resource name of the membership, assigned by the server. Format: `spaces/{space}/members/{member}`"
        },
        "deleteTime": {
          "type": "string",
          "description": "Optional. Immutable. The deletion time of the membership, such as when a member left or was removed from a space. This field is output only, except when used to import historical memberships in import mode spaces.",
          "format": "google-datetime"
        },
        "member": {
          "$ref": "#/$defs/User",
          "description": "Optional. The Google Chat user or app the membership corresponds to. If your Chat app [authenticates as a user](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user), the output only populates the [user](https://developers.google.com/workspace/chat/api/reference/rest/v1/User) `name` and `type` fields for both internal and external users, unless they are members of the space or have a prior affinity, like a direct message (DM) conversation, with the calling user."
        },
        "groupMember": {
          "$ref": "#/$defs/Group",
          "description": "Optional. The Google Group the membership corresponds to. Reading or mutating memberships for Google Groups requires [user authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user)."
        },
        "state": {
          "enum": [
            "MEMBERSHIP_STATE_UNSPECIFIED",
            "JOINED",
            "INVITED",
            "NOT_A_MEMBER"
          ],
          "readOnly": true,
          "description": "Output only. State of the membership.",
          "type": "string"
        },
        "affiliation": {
          "type": "string",
          "readOnly": true,
          "description": "Output only. A user's relationship to the Workspace organization that owns the space. In spaces owned by consumer accounts, the affiliation of all members is `EXTERNAL`.",
          "enum": [
            "AFFILIATION_UNSPECIFIED",
            "INTERNAL",
            "EXTERNAL",
            "MANAGED_EXTERNAL"
          ]
        },
        "role": {
          "type": "string",
          "description": "Optional. User's role within a Chat space, which determines their permitted actions in the space. This field can only be used as input in `UpdateMembership`.",
          "enum": [
            "MEMBERSHIP_ROLE_UNSPECIFIED",
            "ROLE_MEMBER",
            "ROLE_MANAGER",
            "ROLE_ASSISTANT_MANAGER"
          ]
        },
        "createTime": {
          "description": "Optional. Immutable. The creation time of the membership, such as when a member joined or was invited to join a space. This field is output only, except when used to import historical memberships in import mode spaces.",
          "type": "string",
          "format": "google-datetime"
        }
      },
      "description": "Represents a membership relation in Google Chat, such as whether a user or Chat app is invited to, part of, or absent from a space."
    },
    "MembershipCount": {
      "properties": {
        "joinedDirectHumanUserCount": {
          "type": "integer",
          "format": "int32",
          "readOnly": true,
          "description": "Output only. Count of human users that have directly joined the space, not counting users joined by having membership in a joined group."
        },
        "joinedGroupCount": {
          "readOnly": true,
          "description": "Output only. Count of all groups that have directly joined the space.",
          "format": "int32",
          "type": "integer"
        }
      },
      "type": "object",
      "description": "Represents the count of memberships of a space, grouped into categories."
    },
    "PermissionSetting": {
      "properties": {
        "membersAllowed": {
          "description": "Optional. Whether basic space members (`ROLE_MEMBER`) have this permission.",
          "type": "boolean"
        },
        "managersAllowed": {
          "type": "boolean",
          "description": "Optional. Whether space owners (`ROLE_MANAGER`) have this permission."
        },
        "assistantManagersAllowed": {
          "description": "Optional. Whether space managers `ROLE_ASSISTANT_MANAGER`) have this permission.",
          "type": "boolean"
        }
      },
      "description": "Represents a space permission setting.",
      "type": "object"
    },
    "PermissionSettings": {
      "properties": {
        "manageApps": {
          "$ref": "#/$defs/PermissionSetting",
          "description": "Optional. Setting for managing apps in a space."
        },
        "useAtMentionAll": {
          "$ref": "#/$defs/PermissionSetting",
          "description": "Optional. Setting for using @all in a space."
        },
        "manageWebhooks": {
          "$ref": "#/$defs/PermissionSetting",
          "description": "Optional. Setting for managing webhooks in a space."
        },
        "replyMessages": {
          "$ref": "#/$defs/PermissionSetting",
          "description": "Optional. Setting for replying to messages in a space."
        },
        "toggleHistory": {
          "$ref": "#/$defs/PermissionSetting",
          "description": "Optional. Setting for toggling space history on and off."
        },
        "manageMembersAndGroups": {
          "$ref": "#/$defs/PermissionSetting",
          "description": "Optional. Setting for managing members and groups in a space."
        },
        "postMessages": {
          "$ref": "#/$defs/PermissionSetting",
          "description": "Output only. Setting for posting messages in a space."
        },
        "viewSpaceMembership": {
          "$ref": "#/$defs/PermissionSetting",
          "description": "Optional. Setting for viewing space membership. Must be specified together with `AccessPermissionSettings.view_space_membership_setting` in the update mask and request body when updating who can view space membership. When restricting view access to specific roles (for example, space managers or assistant managers only), specify the desired role permissions here and provide an empty `AccessPermissionSettings.view_space_membership_setting` in the same request. If a target audience is configured in `AccessPermissionSettings.view_space_membership_setting`, this setting must be granted to all members."
        },
        "modifySpaceDetails": {
          "$ref": "#/$defs/PermissionSetting",
          "description": "Optional. Setting for updating space name, avatar, description and guidelines."
        }
      },
      "description": "[Permission settings](https://support.google.com/chat/answer/13340792) that you can specify when updating an existing named space. To set permission settings when creating a space, specify the `PredefinedPermissionSettings` field in your request.",
      "type": "object"
    },
    "Principal": {
      "type": "object",
      "description": "A principal representing an entity granted access.",
      "properties": {
        "audience": {
          "$ref": "#/$defs/Audience",
          "description": "An audience."
        }
      }
    },
    "Space": {
      "properties": {
        "singleUserBotDm": {
          "description": "Optional. Whether the space is a DM between a Chat app and a single human.",
          "type": "boolean"
        },
        "type": {
          "type": "string",
          "description": "Output only. Deprecated: Use `space_type` instead. The type of a space.",
          "readOnly": true,
          "enum": [
            "TYPE_UNSPECIFIED",
            "ROOM",
            "DM"
          ],
          "deprecated": true
        },
        "spaceDetails": {
          "$ref": "#/$defs/SpaceDetails",
          "description": "Optional. Details about the space including description and rules."
        },
        "customer": {
          "type": "string",
          "description": "Optional. Immutable. The customer id of the domain of the space. Required only when creating a space with [app authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-app) and `SpaceType` is `SPACE`, otherwise should not be set. In the format `customers/{customer}`, where `customer` is the `id` from the [Admin SDK customer resource](https://developers.google.com/admin-sdk/directory/reference/rest/v1/customers). Private apps can also use the `customers/my_customer` alias to create the space in the same Google Workspace organization as the app. This field isn't populated for direct messages (DMs) or when the space is created by non-Google Workspace users."
        },
        "accessSettings": {
          "$ref": "#/$defs/AccessSettings",
          "description": "Optional. Specifies the [access setting](https://support.google.com/chat/answer/11971020) of the space. Only populated when the `space_type` is `SPACE`."
        },
        "spaceType": {
          "enum": [
            "SPACE_TYPE_UNSPECIFIED",
            "SPACE",
            "GROUP_CHAT",
            "DIRECT_MESSAGE"
          ],
          "description": "Optional. The type of space. Required when creating a space or updating the space type of a space. Output only for other usage.",
          "type": "string"
        },
        "importMode": {
          "description": "Optional. Whether this space is created in `Import Mode` as part of a data migration into Google Workspace. While spaces are being imported, they aren't visible to users until the import is complete. Creating a space in `Import Mode`requires [user authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user).",
          "type": "boolean"
        },
        "membershipCount": {
          "$ref": "#/$defs/MembershipCount",
          "description": "Output only. The count of joined memberships grouped by member type. Populated when the `space_type` is `SPACE`, `DIRECT_MESSAGE` or `GROUP_CHAT`."
        },
        "lastActiveTime": {
          "type": "string",
          "format": "google-datetime",
          "description": "Output only. Timestamp of the last message in the space.",
          "readOnly": true
        },
        "externalUserAllowed": {
          "type": "boolean",
          "description": "Optional. Immutable. Whether this space permits any Google Chat user as a member. Input when creating a space in a Google Workspace organization. Omit this field when creating spaces in the following conditions: * The authenticated user uses a consumer account (unmanaged user account). By default, a space created by a consumer account permits any Google Chat user. For existing spaces, this field is output only."
        },
        "adminInstalled": {
          "description": "Output only. For direct message (DM) spaces with a Chat app, whether the space was created by a Google Workspace administrator. Administrators can install and set up a direct message with a Chat app on behalf of users in their organization. To support admin install, your Chat app must feature direct messaging.",
          "type": "boolean",
          "readOnly": true
        },
        "spaceUri": {
          "type": "string",
          "readOnly": true,
          "description": "Output only. The URI for a user to access the space."
        },
        "name": {
          "type": "string",
          "description": "Identifier. Resource name of the space. Format: `spaces/{space}` Where `{space}` represents the system-assigned ID for the space. You can obtain the space ID by calling the [`spaces.list()`](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces/list) method or from the space URL. For example, if the space URL is `https://mail.google.com/mail/u/0/#chat/space/AAAAAAAAA`, the space ID is `AAAAAAAAA`."
        },
        "spaceThreadingState": {
          "enum": [
            "SPACE_THREADING_STATE_UNSPECIFIED",
            "THREADED_MESSAGES",
            "GROUPED_MESSAGES",
            "UNTHREADED_MESSAGES"
          ],
          "readOnly": true,
          "description": "Output only. The threading state in the Chat space.",
          "type": "string"
        },
        "permissionSettings": {
          "$ref": "#/$defs/PermissionSettings",
          "description": "Optional. Space permission settings for existing spaces. Input for updating exact space permission settings, where existing permission settings are replaced. Output lists current permission settings. Reading and updating permission settings supports: - [App authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-app) with [administrator approval](https://support.google.com/a?p=chat-app-auth) with the `chat.app.spaces` scope. Only populated and settable when the Chat app created the space. - [User authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user)"
        },
        "threaded": {
          "type": "boolean",
          "description": "Output only. Deprecated: Use `spaceThreadingState` instead. Whether messages are threaded in this space.",
          "readOnly": true,
          "deprecated": true
        },
        "displayName": {
          "description": "Optional. The space's display name. Required when [creating a space](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces/create) with a `spaceType` of `SPACE`. If you receive the error message `ALREADY_EXISTS` when creating a space or updating the `displayName`, try a different `displayName`. An existing space within the Google Workspace organization might already use this display name. For direct messages, this field might be empty. Supports up to 128 characters.",
          "type": "string"
        },
        "spaceHistoryState": {
          "type": "string",
          "description": "Optional. The message history state for messages and threads in this space.",
          "enum": [
            "HISTORY_STATE_UNSPECIFIED",
            "HISTORY_OFF",
            "HISTORY_ON"
          ]
        },
        "predefinedPermissionSettings": {
          "description": "Optional. Input only. Predefined space permission settings, input only when creating a space. If the field is not set, a collaboration space is created. After you create the space, settings are populated in the `PermissionSettings` field. Setting predefined permission settings supports: - [App authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-app) with [administrator approval](https://support.google.com/a?p=chat-app-auth) with the `chat.app.spaces` or `chat.app.spaces.create` scopes. - [User authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user)",
          "enum": [
            "PREDEFINED_PERMISSION_SETTINGS_UNSPECIFIED",
            "COLLABORATION_SPACE",
            "ANNOUNCEMENT_SPACE"
          ],
          "type": "string"
        },
        "createTime": {
          "format": "google-datetime",
          "description": "Optional. Immutable. For spaces created in Chat, the time the space was created. This field is output only, except when used in import mode spaces. For import mode spaces, set this field to the historical timestamp at which the space was created in the source in order to preserve the original creation time. Only populated in the output when `spaceType` is `GROUP_CHAT` or `SPACE`.",
          "type": "string"
        },
        "importModeExpireTime": {
          "readOnly": true,
          "format": "google-datetime",
          "type": "string",
          "description": "Output only. The time when the space will be automatically deleted by the system if it remains in import mode. Each space created in import mode must exit this mode before this expire time using `spaces.completeImport`. This field is only populated for spaces that were created with import mode."
        }
      },
      "type": "object",
      "description": "A space in Google Chat. Spaces are conversations between two or more users or 1:1 messages between a user and a Chat app."
    },
    "SpaceDetails": {
      "description": "Details about the space including description and rules.",
      "type": "object",
      "properties": {
        "description": {
          "type": "string",
          "description": "Optional. A description of the space. For example, describe the space's discussion topic, functional purpose, or participants. Supports up to 4,096 characters."
        },
        "guidelines": {
          "description": "Optional. The space's rules, expectations, and etiquette. Supports up to 5,000 characters.",
          "type": "string"
        }
      }
    },
    "User": {
      "description": "If your Chat app [authenticates as a user](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user), the output for a `User` resource (such as in the Messages and Memberships APIs) only populates the `name` and `type` fields for both internal and external users, unless they are members of the space or have prior affinity with the calling user.",
      "properties": {
        "displayName": {
          "readOnly": true,
          "type": "string",
          "description": "Output only. The user's display name. Populated for both app authentication and user authentication. This field is always populated for requests made with [app authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-app). When calling the Messages and Memberships APIs with [user authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user), this field is populated for both internal and external users for the `sender` of a message, users within `annotations` (such as user mentions), and within `Membership` resources, provided the user is a member of the space or has prior affinity with the calling user."
        },
        "type": {
          "enum": [
            "TYPE_UNSPECIFIED",
            "HUMAN",
            "BOT"
          ],
          "type": "string",
          "description": "User type."
        },
        "name": {
          "type": "string",
          "description": "Resource name for a Google Chat user. Format: `users/{user}`. `users/app` can be used as an alias for the calling app bot user. For human users, `{user}` is the same user identifier as: - the `id` for the [Person](https://developers.google.com/people/api/rest/v1/people) in the People API. For example, `users/123456789` in Chat API represents the same person as the `123456789` Person profile ID in People API. - the `id` for a [user](https://developers.google.com/admin-sdk/directory/reference/rest/v1/users) in the Admin SDK Directory API. - the user's email address can be used as an alias for `{user}` in API requests. For example, if the People API Person profile ID for `user@example.com` is `123456789`, you can use `users/user@example.com` as an alias to reference `users/123456789`. Only the canonical resource name (for example `users/123456789`) will be returned from the API."
        },
        "avatarUrl": {
          "readOnly": true,
          "type": "string",
          "description": "Output only. The user's avatar image URL. When calling the Messages and Memberships APIs with [user authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user), this field is populated for both internal and external users for the `sender` of a message, users within `annotations` (such as user mentions), and within `Membership` resources, provided the user is a member of the space or has prior affinity with the calling user."
        },
        "email": {
          "type": "string",
          "description": "Output only. The user's email address. When calling the Messages and Memberships APIs with [user authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user), this field is populated for both internal and external users for the `sender` of a message, users within `annotations` (such as user mentions), and within `Membership` resources, provided the user is a member of the space or has prior affinity with the calling user.",
          "readOnly": true
        },
        "domainId": {
          "description": "Unique identifier of the user's Google Workspace domain.",
          "type": "string"
        },
        "isAnonymous": {
          "readOnly": true,
          "type": "boolean",
          "description": "Output only. When `true`, the user is deleted or their profile is not visible, such as when a user is mentioned in a space without being a member and without prior affinity with the calling user."
        }
      },
      "type": "object"
    }
  }
}