> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gomry.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Space

> Create a new space in your organization

# Create Space

Creates a new space in your organization. The created space is **immediately
usable** as a `space_identifier` on [Create Event](/api-reference/events/create-event),
[Create Experience](/api-reference/experiences/create-experience), and the other
space-scoped endpoints.

This is the building block for the **merchant-of-record / marketplace** pattern:
provision one space per seller, then set each space's tax and legal-entity
details with [Set Tax Details](/api-reference/spaces/set-tax-details) so receipts
and VAT are attributed correctly.

Requires the `spaces:write` scope.

<Note>
  `identifier` must be unique within your organization and is used verbatim as
  `space_identifier` elsewhere. `name` must also be unique (case-insensitive).
  `GENERAL` is reserved for the organization-wide scope and cannot be used.
</Note>

## Idempotency

Pass an `Idempotency-Key` header (max 255 chars) to make POST retries safe. The first request executes the create; subsequent requests with the same key within 24 hours replay the original response verbatim — including the original status code — and add an `Idempotent-Replay: true` response header. Keys are scoped per API key.

Two concurrent requests with the same key return `409 idempotent_request_in_progress` to the second caller.

## Request Body

<ParamField body="name" type="string" required>
  Display name (max 200 chars). Must be unique within the organization
  (case-insensitive).
</ParamField>

<ParamField body="identifier" type="string" required>
  URL-safe slug used as `space_identifier` elsewhere. 1–64 characters:
  letters, numbers, hyphen (`-`) or underscore (`_`). Must be unique within
  the organization. `GENERAL` is reserved.
</ParamField>

<ParamField body="color" type="string">
  Accent color token. Defaults to `zinc`.
</ParamField>

<ParamField body="icon" type="string">
  Icon name or emoji. Defaults to `general`.
</ParamField>

<ParamField body="icon_type" type="string">
  `emoji` or `icon`. Defaults to `emoji`.
</ParamField>

<ParamField body="email" type="string">
  Contact email for the space (shown on receipts).
</ParamField>

<ParamField body="linkedin" type="string">Social profile URL.</ParamField>
<ParamField body="instagram" type="string">Social profile URL.</ParamField>
<ParamField body="facebook" type="string">Social profile URL.</ParamField>
<ParamField body="twitter" type="string">Social profile URL.</ParamField>
<ParamField body="website" type="string">Website URL.</ParamField>

## Response

Returns the created space with `201 Created` — same schema as
[Get Space](/api-reference/spaces/get-space). Tax details start `null`; set them
with [Set Tax Details](/api-reference/spaces/set-tax-details).

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST \
    -H "X-API-KEY: your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Milan",
      "identifier": "milan",
      "email": "milan@acme.com"
    }' \
    "https://www.gomry.com/api/v1/spaces"
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "data": {
      "id": "AbCdEfGhIjKlMnOpQrSt",
      "identifier": "milan",
      "name": "Milan",
      "status": "active",
      "color": "zinc",
      "icon": "general",
      "icon_type": "emoji",
      "email": "milan@acme.com",
      "tax_details": null,
      "created_at": "2025-07-15T10:00:00.000Z",
      "updated_at": "2025-07-15T10:00:00.000Z"
    }
  }
  ```

  ```json 400 theme={null}
  {
    "error": "Validation failed",
    "details": { "fieldErrors": { "identifier": ["identifier must be 1–64 chars: letters, numbers, hyphen or underscore"] } }
  }
  ```

  ```json 409 theme={null}
  {
    "error": "Space already exists",
    "details": { "identifier": "A space with this identifier already exists" }
  }
  ```

  ```json 403 theme={null}
  {
    "error": "insufficient_scope",
    "message": "This API key does not have 'write' access to 'spaces'.",
    "required_scope": "spaces:write"
  }
  ```
</ResponseExample>