---
title: "Create space"
method: POST
path: "/spaces"
tags: ["Space"]
---

# Create space

`POST /spaces`

Creates a Space as specified in the payload.

Available on tenants with [Role-Based Access Control](https://support.atlassian.com/confluence-cloud/docs/manage-user-roles/). 

**[Permissions](https://confluence.atlassian.com/x/_AozKw) required**:
Permission to create spaces.

## Request body

- object
  - `name` string, required — The name of the space to be created.
  - `key` string — The key for the new space. See [Space Keys](https://support.atlassian.com/confluence-cloud/docs/create-a-space/). If the key property is not provided, the alias property is required to be used instead.
  - `alias` string — This field will be used as the new identifier for the space in confluence page URLs. If the alias property is not provided, the key property is required to be used instead. Maximum 255 alphanumeric characters in length.
  - `description` object — The description of the new/updated space. Note, only the 'plain' representation is currently supported.
    - `value` string — The space description.
    - `representation` string — The format of the description.
  - `roleAssignments` object[]
    - `principal` Principal — The principal of the role assignment.
      - `principalType` 'USER' | 'GROUP' | 'ACCESS_CLASS' — The principal type.
      - `principalId` string — The principal ID.
    - `roleId` string — The role to which the principal is assigned.
  - `copySpaceAccessConfiguration` integer — The id of the space to copy the space access configuration from.
  - `createPrivateSpace` boolean — Whether to create the space as private.
  - `templateKey` string — The key of the template to use.

## Response `201`

Returned if the requested space is created.

- object
  - `id` string — ID of the space.
  - `key` string — Key of the space.
  - `name` string — Name of the space.
  - `type` 'global' | 'collaboration' | 'knowledge_base' | 'personal' | 'system' | 'onboarding' | 'xflow_sample_space' — The type of space.
  - `status` 'current' | 'archived' — The status of the space.
  - `authorId` string — The account ID of the user who created this space originally.
  - `spaceOwnerId` string — The account ID of the user who owns this space.
  - `currentActiveAlias` string — Currently active alias for a Confluence space.
  - `createdAt` string, date-time — Date and time when the space was created. In format "YYYY-MM-DDTHH:mm:ss.sssZ".
  - `homepageId` string — ID of the space's homepage.
  - `description` SpaceDescription — Contains fields for each representation type requested.
    - `plain` BodyType
      - `representation` string — Type of content representation used for the value field.
      - `value` string — Body of the content, in the format found in the representation field.
    - `view` BodyType
      - `representation` string — Type of content representation used for the value field.
      - `value` string — Body of the content, in the format found in the representation field.
  - `icon` SpaceIcon — The icon of the space
    - `path` string — The path (relative to base URL) at which the space's icon can be retrieved. The format should be like `/wiki/download/...` or `/wiki/aa-avatar/...`
    - `apiDownloadLink` string — The path (relative to base URL) that can be used to retrieve a link to download the space icon. 3LO apps should use this link instead of the value provided in the `path` property to retrieve the icon. Currently this field is only returned for `global` spaces and not `personal` spaces.
  - `_links` object
    - `webui` string — Web UI link of the space.
    - `base` string — Base url of the Confluence site.

## Other responses

- `400` — Returned if an invalid request is provided.
- `401` — Returned if the authentication credentials are incorrect or missing from the request.
- `404` — Returned if the calling user does not have permission to create spaces.
- `413` — Returned if the request is too large in size (over 5 MB).

---

[API](https://skmtc.net/atlassian/apis/the-confluence-cloud-rest-api-v2.md) · [All operations](https://skmtc.net/atlassian/apis/the-confluence-cloud-rest-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/atlassian/the-confluence-cloud-rest-api-v2/revisions/c4bd1ed570f2/schema)