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

# Create space

`POST /v1/spaces`

Creates a new space based on a supplied name and description in the JSON request body. The endpoint is subject to rate limiting and automatically applies default configurations such as generating a random icon and initializing the workspace with default settings (for example, a default dashboard or home page). On success, the new space’s full metadata is returned, enabling the client to immediately switch context to the new internal.

## Headers

- `Anytype-Version` string, required

## Request body

- CreateSpaceRequest
  - `description` string — The description of the space
  - `name` string, required — The name of the space

## Response `201`

The created space

- SpaceResponse
  - `space` Space — The space
    - `description` string — The description of the space
    - `gateway_url` string — The gateway url to serve files and media
    - `icon` union — The icon of the object, or null if the object has no icon
      - object
        - `emoji` string — The emoji of the icon
        - `format` 'emoji' | 'file' | 'icon' — The format of the icon
      - object
        - `file` string — The file of the icon
        - `format` 'emoji' | 'file' | 'icon' — The format of the icon
      - object
        - `color` 'grey' | 'yellow' | 'orange' | 'red' | 'pink' | 'purple' | 'blue' | 'ice' | 'teal' | 'lime' — The color of the icon
        - `format` 'emoji' | 'file' | 'icon' — The format of the icon
        - `name` 'accessibility' | 'add-circle' | 'airplane' | 'alarm' | 'albums' | 'alert-circle' | 'american-football' | 'analytics' | 'aperture' | 'apps' | 'archive' | 'arrow-back-circle' | 'arrow-down-circle' | 'arrow-forward-circle' | 'arrow-redo-circle' | 'arrow-redo' | 'arrow-undo-circle' | 'arrow-undo' | 'arrow-up-circle' | 'at-circle' | 'attach' | 'backspace' | 'bag-add' | 'bag-check' | 'bag-handle' | 'bag-remove' | 'bag' | 'balloon' | 'ban' | 'bandage' | 'bar-chart' | 'barbell' | 'barcode' | 'baseball' | 'basket' | 'basketball' | 'battery-charging' | 'battery-dead' | 'battery-full' | 'battery-half' | 'beaker' | 'bed' | 'beer' | 'bicycle' | 'binoculars' | 'bluetooth' | 'boat' | 'body' | 'bonfire' | 'book' | 'bookmark' | 'bookmarks' | 'bowling-ball' | 'briefcase' | 'browsers' | 'brush' | 'bug' | 'build' | 'bulb' | 'bus' | 'business' | 'cafe' | 'calculator' | 'calendar-clear' | 'calendar-number' | 'calendar' | 'call' | 'camera-reverse' | 'camera' | 'car-sport' | 'car' | 'card' | 'caret-back-circle' | 'caret-back' | 'caret-down-circle' | 'caret-down' | 'caret-forward-circle' | 'caret-forward' | 'caret-up-circle' | 'caret-up' | 'cart' | 'cash' | 'cellular' | 'chatbox-ellipses' | 'chatbox' | 'chatbubble-ellipses' | 'chatbubble' | 'chatbubbles' | 'checkbox' | 'checkmark-circle' | 'checkmark-done-circle' | 'chevron-back-circle' | 'chevron-down-circle' | 'chevron-forward-circle' | 'chevron-up-circle' | 'clipboard' | 'close-circle' | 'cloud-circle' | 'cloud-done' | 'cloud-download' | 'cloud-offline' | 'cloud-upload' | 'cloud' | 'cloudy-night' | 'cloudy' | 'code-slash' | 'code' | 'cog' | 'color-fill' | 'color-filter' | 'color-palette' | 'color-wand' | 'compass' | 'construct' | 'contact' | 'contract' | 'contrast' | 'copy' | 'create' | 'crop' | 'cube' | 'cut' | 'desktop' | 'diamond' | 'dice' | 'disc' | 'document-attach' | 'document-lock' | 'document-text' | 'document' | 'documents' | 'download' | 'duplicate' | 'ear' | 'earth' | 'easel' | 'egg' | 'ellipse' | 'ellipsis-horizontal-circle' | 'ellipsis-vertical-circle' | 'enter' | 'exit' | 'expand' | 'extension-puzzle' | 'eye-off' | 'eye' | 'eyedrop' | 'fast-food' | 'female' | 'file-tray-full' | 'file-tray-stacked' | 'file-tray' | 'film' | 'filter-circle' | 'finger-print' | 'fish' | 'fitness' | 'flag' | 'flame' | 'flash-off' | 'flash' | 'flashlight' | 'flask' | 'flower' | 'folder-open' | 'folder' | 'football' | 'footsteps' | 'funnel' | 'game-controller' | 'gift' | 'git-branch' | 'git-commit' | 'git-compare' | 'git-merge' | 'git-network' | 'git-pull-request' | 'glasses' | 'globe' | 'golf' | 'grid' | 'hammer' | 'hand-left' | 'hand-right' | 'happy' | 'hardware-chip' | 'headset' | 'heart-circle' | 'heart-dislike-circle' | 'heart-dislike' | 'heart-half' | 'heart' | 'help-buoy' | 'help-circle' | 'home' | 'hourglass' | 'ice-cream' | 'id-card' | 'image' | 'images' | 'infinite' | 'information-circle' | 'invert-mode' | 'journal' | 'key' | 'keypad' | 'language' | 'laptop' | 'layers' | 'leaf' | 'library' | 'link' | 'list-circle' | 'list' | 'locate' | 'location' | 'lock-closed' | 'lock-open' | 'log-in' | 'log-out' | 'logo-alipay' | 'logo-amazon' | 'logo-amplify' | 'logo-android' | 'magnet' | 'mail-open' | 'mail-unread' | 'mail' | 'male-female' | 'male' | 'man' | 'map' | 'medal' | 'medical' | 'medkit' | 'megaphone' | 'menu' | 'mic-circle' | 'mic-off-circle' | 'mic-off' | 'mic' | 'moon' | 'move' | 'musical-note' | 'musical-notes' | 'navigate-circle' | 'navigate' | 'newspaper' | 'notifications-circle' | 'notifications-off-circle' | 'notifications-off' | 'notifications' | 'nuclear' | 'nutrition' | 'options' | 'paper-plane' | 'partly-sunny' | 'pause-circle' | 'pause' | 'paw' | 'pencil' | 'people-circle' | 'people' | 'person-add' | 'person-circle' | 'person-remove' | 'person' | 'phone-landscape' | 'phone-portrait' | 'pie-chart' | 'pin' | 'pint' | 'pizza' | 'planet' | 'play-back-circle' | 'play-back' | 'play-circle' | 'play-forward-circle' | 'play-forward' | 'play-skip-back-circle' | 'play-skip-back' | 'play-skip-forward-circle' | 'play-skip-forward' | 'play' | 'podium' | 'power' | 'pricetag' | 'pricetags' | 'print' | 'prism' | 'pulse' | 'push' | 'qr-code' | 'radio-button-off' | 'radio-button-on' | 'radio' | 'rainy' | 'reader' | 'receipt' | 'recording' | 'refresh-circle' | 'refresh' | 'reload-circle' | 'reload' | 'remove-circle' | 'repeat' | 'resize' | 'restaurant' | 'ribbon' | 'rocket' | 'rose' | 'sad' | 'save' | 'scale' | 'scan-circle' | 'scan' | 'school' | 'search-circle' | 'search' | 'send' | 'server' | 'settings' | 'shapes' | 'share-social' | 'share' | 'shield-checkmark' | 'shield-half' | 'shield' | 'shirt' | 'shuffle' | 'skull' | 'snow' | 'sparkles' | 'speedometer' | 'square' | 'star-half' | 'star' | 'stats-chart' | 'stop-circle' | 'stop' | 'stopwatch' | 'storefront' | 'subway' | 'sunny' | 'swap-horizontal' | 'swap-vertical' | 'sync-circle' | 'sync' | 't.txt' | 'tablet-landscape' | 'tablet-portrait' | 'telescope' | 'tennisball' | 'terminal' | 'text' | 'thermometer' | 'thumbs-down' | 'thumbs-up' | 'thunderstorm' | 'ticket' | 'time' | 'timer' | 'today' | 'toggle' | 'trail-sign' | 'train' | 'transgender' | 'trash-bin' | 'trash' | 'trending-down' | 'trending-up' | 'triangle' | 'trophy' | 'tv' | 'umbrella' | 'unlink' | 'videocam-off' | 'videocam' | 'volume-high' | 'volume-low' | 'volume-medium' | 'volume-mute' | 'volume-off' | 'walk' | 'wallet' | 'warning' | 'watch' | 'water' | 'wifi' | 'wine' | 'woman' — The name of the icon
    - `id` string — The id of the space
    - `name` string — The name of the space
    - `network_id` string — The network id of the space
    - `object` 'space' | 'chat' — The data model of the object

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `429` — Rate limit exceeded
- `500` — Internal server error

## Changes

- **2026-01-07** `f701c48d380c` — 2 breaking, 2 warning, 1 info
  - the response property `space/icon` became nullable for the status `201`
  - added `#/components/schemas/EmojiIcon, #/components/schemas/FileIcon, #/components/schemas/NamedIcon` to the `space/icon` response property `oneOf` list for the response status `201`
  - added the new `chat` enum value to the `space/object` response property for the response status `201`
  - added the new `space` enum value to the `space/object` response property for the response status `201`
  - …1 more
- **2025-05-18** `65011ed70b4c` — 1 breaking, 1 info
  - removed the success response with the status `200`
  - added the success response with the status `201`
- **2025-05-16** `777c86c4db5d` — 6 warning
  - added the new `emoji` enum value to the `space/icon/oneOf[#/components/schemas/apimodel.EmojiIcon]/format` response property for the response status `200`
  - added the new `emoji` enum value to the `space/icon/oneOf[#/components/schemas/apimodel.FileIcon]/format` response property for the response status `200`
  - added the new `emoji` enum value to the `space/icon/oneOf[#/components/schemas/apimodel.NamedIcon]/format` response property for the response status `200`
  - added the new `file` enum value to the `space/icon/oneOf[#/components/schemas/apimodel.EmojiIcon]/format` response property for the response status `200`
  - …2 more
- …earlier changes not shown

[Full history](https://skmtc.dev/anyproto/apis/anytype-api/changes/v1/spaces/post.md)

---

[API](https://skmtc.dev/anyproto/apis/anytype-api.md) · [All operations](https://skmtc.dev/anyproto/apis/anytype-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/anyproto/anytype-api/revisions/6f8ebf2b819a/schema)