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"
{
"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"
}
}
{
"error": "Validation failed",
"details": { "fieldErrors": { "identifier": ["identifier must be 1–64 chars: letters, numbers, hyphen or underscore"] } }
}
{
"error": "Space already exists",
"details": { "identifier": "A space with this identifier already exists" }
}
{
"error": "insufficient_scope",
"message": "This API key does not have 'write' access to 'spaces'.",
"required_scope": "spaces:write"
}
Spaces
Create Space
Create a new space in your organization
POST
/
spaces
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"
{
"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"
}
}
{
"error": "Validation failed",
"details": { "fieldErrors": { "identifier": ["identifier must be 1–64 chars: letters, numbers, hyphen or underscore"] } }
}
{
"error": "Space already exists",
"details": { "identifier": "A space with this identifier already exists" }
}
{
"error": "insufficient_scope",
"message": "This API key does not have 'write' access to 'spaces'.",
"required_scope": "spaces:write"
}
Create Space
Creates a new space in your organization. The created space is immediately usable as aspace_identifier on Create Event,
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 so receipts
and VAT are attributed correctly.
Requires the spaces:write scope.
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.Idempotency
Pass anIdempotency-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
string
required
Display name (max 200 chars). Must be unique within the organization
(case-insensitive).
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.string
Accent color token. Defaults to
zinc.string
Icon name or emoji. Defaults to
general.string
emoji or icon. Defaults to emoji.string
Contact email for the space (shown on receipts).
string
Social profile URL.
string
Social profile URL.
string
Social profile URL.
string
Social profile URL.
string
Website URL.
Response
Returns the created space with201 Created — same schema as
Get Space. Tax details start null; set them
with Set Tax Details.
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"
{
"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"
}
}
{
"error": "Validation failed",
"details": { "fieldErrors": { "identifier": ["identifier must be 1–64 chars: letters, numbers, hyphen or underscore"] } }
}
{
"error": "Space already exists",
"details": { "identifier": "A space with this identifier already exists" }
}
{
"error": "insufficient_scope",
"message": "This API key does not have 'write' access to 'spaces'.",
"required_scope": "spaces:write"
}