Gather HTTP API
Create Gather spaces, read and write the map/room data of a space, and manage a space's email guestlist. Authenticated with an apiKey header.
OpenAPI Specification
openapi: 3.0.3
info:
title: Gather HTTP API
version: '2.0'
description: >-
The Gather HTTP API lets you read and write the map/room data of a Gather
space and manage its email guestlist programmatically, enabling dynamically
and programmatically generated maps. Authentication is via an API key
generated at https://gather.town/apiKeys; the caller must have Admin or
Builder permission on the space being modified. This description was
reconstructed by the API Evangelist enrichment pipeline from Gather's
official public documentation (Notion HTTP API reference) and the
gathertown/api-examples repository — it captures the documented,
verified operations and is not an official Gather OpenAPI document.
x-provenance:
generated: '2026-07-19'
method: derived
source:
- https://gathertown.notion.site/Gather-HTTP-API-3bbf6c59325f40aca7ef5ce14c677444
- https://github.com/gathertown/api-examples
contact:
name: Gather Support
url: https://support.gather.town/
servers:
- url: https://api.gather.town
description: Gather HTTP API
security:
- apiKey: []
tags:
- name: Spaces
description: Create and manage Gather spaces
- name: Maps
description: Read and write the map/room data of a space
- name: Guestlist
description: Manage the email guestlist (members/guests) of a space
paths:
/api/v2/spaces:
post:
operationId: createSpace
summary: Create a space
description: >-
Create a new Gather space, optionally cloning an existing space passed
as sourceSpace. Requires an API key with sufficient permission.
tags: [Spaces]
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: Display name for the new space.
sourceSpace:
type: string
description: Space ID to clone the new space from.
required: [name]
responses:
'200':
description: The created space identifier.
content:
application/json:
schema:
type: object
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
/api/v2/spaces/{spaceId}/maps/{mapId}:
parameters:
- $ref: '#/components/parameters/SpaceId'
- $ref: '#/components/parameters/MapId'
get:
operationId: getMap
summary: Get map
description: Retrieve the full map/room data for a given map within a space.
tags: [Maps]
parameters:
- name: useV2Map
in: query
required: false
schema:
type: boolean
description: Return the v2 map representation.
responses:
'200':
description: The map document.
content:
application/json:
schema:
$ref: '#/components/schemas/Map'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
post:
operationId: setMap
summary: Set map
description: >-
Overwrite the map/room data for a given map within a space. The request
body carries the new map content (background image, objects, spawns,
impassable tiles, and more).
tags: [Maps]
parameters:
- name: useV2Map
in: query
required: false
schema:
type: boolean
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
content:
$ref: '#/components/schemas/Map'
responses:
'200':
description: Map updated.
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
/api/getEmailGuestlist:
get:
operationId: getEmailGuestlist
summary: Get email guestlist
description: >-
Retrieve the email guestlist for a space — a JSON object keyed by email
address, each value carrying optional name, affiliation, and role.
tags: [Guestlist]
parameters:
- $ref: '#/components/parameters/SpaceIdQuery'
responses:
'200':
description: The guestlist object.
content:
application/json:
schema:
$ref: '#/components/schemas/Guestlist'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
/api/setEmailGuestlist:
post:
operationId: setEmailGuestlist
summary: Set email guestlist
description: >-
Set or update the email guestlist for a space. When overwrite is false
the supplied entries are merged/appended; when true the guestlist is
replaced.
tags: [Guestlist]
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
spaceId:
type: string
guestlist:
$ref: '#/components/schemas/Guestlist'
overwrite:
type: boolean
description: Replace the guestlist instead of merging.
required: [spaceId, guestlist]
responses:
'200':
description: Guestlist updated.
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: apiKey
description: >-
API key generated at https://gather.town/apiKeys, sent in the apiKey
request header. The associated user must have Admin or Builder
permission on the target space.
parameters:
SpaceId:
name: spaceId
in: path
required: true
schema:
type: string
description: The space identifier (URL-encoded; contains a backslash-delimited id).
MapId:
name: mapId
in: path
required: true
schema:
type: string
description: The map/room identifier within the space.
SpaceIdQuery:
name: spaceId
in: query
required: true
schema:
type: string
description: The space identifier.
responses:
BadRequest:
description: Malformed request (invalid body or parameters).
Forbidden:
description: The API key lacks permission on the target space.
NotFound:
description: The referenced space or map was not found.
schemas:
Map:
type: object
description: Gather map/room document.
properties:
backgroundImagePath:
type: string
spawns:
type: array
items:
type: object
objects:
type: array
items:
type: object
collisions:
type: string
Guestlist:
type: object
description: >-
Object keyed by email address; each value is an object with optional
name, affiliation, and role string fields.
additionalProperties:
type: object
properties:
name:
type: string
affiliation:
type: string
role:
type: string