> For the complete documentation index, see [llms.txt](https://docs.coherence.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coherence.io/2.4/hosting/self-hosting/open-api-reference/rooms.md).

# Rooms

Rooms related operations

## POST /add

> Creates a room instance on the server.

```json
{"openapi":"3.0.4","info":{"title":"Replication Server REST API","version":"v8.0.0"},"tags":[{"name":"rooms","description":"Rooms related operations"}],"servers":[{"url":"http://127.0.0.1:64001","description":"Local Rooms Replication Server"},{"url":"http://127.0.0.1:32004","description":"Local World Replication Server"}],"security":[{"rs_auth":[]}],"components":{"securitySchemes":{"rs_auth":{"type":"http","scheme":"bearer"}},"schemas":{"rooms.AddRequest":{"type":"object","required":["UniqueID","Secret","RecvFrequency","SendFrequency","ProjectID","CleanupTimeout","DisconnectTimeout","MaxClients","MaxEntities","MaxQueriesPerClient"],"properties":{"UniqueID":{"description":"Unique ID of the room instance. This ID is used to identify the room in the server.","type":"integer","format":"int64","minimum":1},"Secret":{"description":"Secret used for authenticating Simulator connections.","type":"string","minLength":4,"maxLength":128},"MaxClients":{"description":"Maximum number of clients allowed to connect to the room instance.","type":"integer","minimum":1,"maximum":65535,"default":10},"MaxEntities":{"description":"Maximum number of entities allowed to be created in the room instance.","type":"integer","minimum":1,"default":65534},"MaxQueriesPerClient":{"description":"Maximum number of queries that each client can have active at any time.","type":"integer","minimum":1,"default":15},"SchemaName":{"description":"Name of the schema to be used for the room instance.","type":"string","default":""},"SchemaTimeout":{"description":"How long (in seconds) the schema should be cached in the server before being removed.","type":"integer","minimum":1,"default":60},"SchemaUrls":{"description":"URLs of the schemas to be used for the room instance.","type":"array","items":{"type":"string"},"default":[]},"Schemas":{"description":"List of schemas to be used for the room instance.","type":"array","items":{"type":"string"},"default":[]},"DisconnectTimeout":{"description":"How long (in milliseconds) the server should wait before closing the connection to a client that hasn't sent any data.","type":"integer","format":"uint32","minimum":1,"default":5000},"DebugStreams":{"description":"Whether to enable debug streams for the room instance.","type":"boolean","default":false},"SendFrequency":{"description":"Frequency (Hz) at which the server should send updates to clients.","type":"integer","minimum":1,"maximum":256,"default":20},"RecvFrequency":{"description":"Frequency (Hz) at which the server expects to receive updates from clients.","type":"integer","format":"uint8","minimum":1,"maximum":255,"default":60},"MinQueryDistance":{"description":"Minimum displacement distance for a query to be considered changed.","type":"number","format":"float","default":0.01},"CleanupTimeout":{"description":"How long (in seconds) the server should wait before removing a room instance that has no active clients.","type":"integer","minimum":1,"default":5},"ProjectID":{"description":"ID of the project to which the room instance belongs.","type":"string"},"KVP":{"description":"Key-Value Pair (KVP) data associated with the room instance. Keys are at most\n128 characters.","type":"object","maxProperties":128,"additionalProperties":{"type":"string","maxLength":128}},"PrivateKVP":{"description":"Private Key-Value Pair (KVP) data associated with the room instance. Keys are\nat most 128 characters.","type":"object","maxProperties":128,"additionalProperties":{"type":"string","maxLength":1024}},"Tags":{"description":"Tags associated with the room instance.","type":"array","items":{"type":"string","maxLength":128},"maxItems":128},"Created":{"description":"Timestamp indicating when the room instance was created.","type":"string","format":"date-time"},"HostAuthority":{"description":"Comma-separated list of host authority features. Valid values are \"create-entities\" and \"validate-connection\". Example \"create-entities,validate-connection\"","type":"string","default":""}}},"rooms.AddResponse":{"type":"object","properties":{"RoomID":{"description":"ID of the room instance as assigned by the server.","type":"integer","format":"uint16","minimum":1,"maximum":65535},"Secret":{"type":"string"}},"required":["RoomID","Secret"]},"Error":{"type":"object","properties":{"error_code":{"description":"Error code indicating the type of error that occurred.","type":"string","enum":["ERR_BAD_REQUEST","ERR_INTERNAL_ERROR","ERR_RESTRICTED_MODE_CAP_REACHED","ERR_ROOMS_LIMIT_REACHED","ERR_INVALID_SCHEMA","ERR_INVALID_ROOM_LIMIT","ERR_INVALID_MAX_ENTITIES","ERR_ROOM_NOT_FOUND","ERR_HIGH_MEMORY_PRESSURE"]},"user_message":{"description":"User-friendly error message.","type":"string"}},"required":["error_code","user_message"]}}},"paths":{"/add":{"post":{"tags":["rooms"],"summary":"Creates a room instance on the server.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/rooms.AddRequest"}}},"required":true},"responses":{"200":{"description":"Room was created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rooms.AddResponse"}}}},"400":{"description":"Bad request; invalid or missing parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized; invalid authentication token"},"500":{"description":"Internal Replication Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service unavailable; server is busy or overloaded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## POST /remove

> Closes a room instance on the server.

```json
{"openapi":"3.0.4","info":{"title":"Replication Server REST API","version":"v8.0.0"},"tags":[{"name":"rooms","description":"Rooms related operations"}],"servers":[{"url":"http://127.0.0.1:64001","description":"Local Rooms Replication Server"},{"url":"http://127.0.0.1:32004","description":"Local World Replication Server"}],"security":[{"rs_auth":[]}],"components":{"securitySchemes":{"rs_auth":{"type":"http","scheme":"bearer"}},"schemas":{"rooms.RemoveRequest":{"type":"object","properties":{"RoomID":{"description":"ID of the room instance as assigned by the server.","type":"integer","format":"uint16","minimum":1,"maximum":65535}},"required":["RoomID"]},"Error":{"type":"object","properties":{"error_code":{"description":"Error code indicating the type of error that occurred.","type":"string","enum":["ERR_BAD_REQUEST","ERR_INTERNAL_ERROR","ERR_RESTRICTED_MODE_CAP_REACHED","ERR_ROOMS_LIMIT_REACHED","ERR_INVALID_SCHEMA","ERR_INVALID_ROOM_LIMIT","ERR_INVALID_MAX_ENTITIES","ERR_ROOM_NOT_FOUND","ERR_HIGH_MEMORY_PRESSURE"]},"user_message":{"description":"User-friendly error message.","type":"string"}},"required":["error_code","user_message"]}}},"paths":{"/remove":{"post":{"tags":["rooms"],"summary":"Closes a room instance on the server.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/rooms.RemoveRequest"}}},"required":true},"responses":{"200":{"description":"Room was closed successfully"},"404":{"description":"Room to be closed was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Replication Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## GET /get

> Fetches the list of rooms on the server.

```json
{"openapi":"3.0.4","info":{"title":"Replication Server REST API","version":"v8.0.0"},"tags":[{"name":"rooms","description":"Rooms related operations"}],"servers":[{"url":"http://127.0.0.1:64001","description":"Local Rooms Replication Server"},{"url":"http://127.0.0.1:32004","description":"Local World Replication Server"}],"security":[{"rs_auth":[]}],"components":{"securitySchemes":{"rs_auth":{"type":"http","scheme":"bearer"}},"schemas":{"rooms.GetRoomsResponse":{"type":"object","properties":{"Rooms":{"description":"List of room instances on the server.","type":"array","items":{"$ref":"#/components/schemas/rooms.RoomInfo"}}}},"rooms.RoomInfo":{"type":"object","properties":{"UniqueID":{"description":"Unique ID of the room instance.","type":"integer","format":"int64","minimum":1},"ID":{"description":"ID of the room instance as assigned by the server.","type":"integer","format":"uint16","minimum":1,"maximum":65535},"MaxClients":{"description":"Maximum number of clients allowed to connect to the room instance.","type":"integer","minimum":1,"maximum":65535},"SchemaName":{"description":"Name of the schema to be used for the room instance.","type":"string"},"ConnectionCount":{"description":"Number of clients currently connected to the room instance.","type":"integer","minimum":0,"maximum":65535},"PlayerIDs":{"description":"Player IDs currently connected to the room instance. Included only when requested.","type":"array","items":{"type":"string"}},"LastCheckTime":{"description":"Timestamp indicating the last time the server checked the room instance.","type":"string","format":"date-time"},"ProjectID":{"description":"ID of the project to which the room instance belongs.","type":"string"},"KVP":{"description":"Key-Value Pair (KVP) data associated with the room instance. Keys are at most\n128 characters.","type":"object","additionalProperties":{"type":"string"}},"PrivateKVP":{"description":"Private Key-Value Pair (KVP) data associated with the room instance. Keys are\nat most 128 characters.","type":"object","additionalProperties":{"type":"string"}},"Tags":{"description":"Tags associated with the room instance.","type":"array","items":{"type":"string"}},"CreatedAt":{"description":"Timestamp indicating when the room instance was created.","type":"string","format":"date-time"},"Secret":{"description":"Secret used for authenticating Simulator connections.","type":"string"}}},"Error":{"type":"object","properties":{"error_code":{"description":"Error code indicating the type of error that occurred.","type":"string","enum":["ERR_BAD_REQUEST","ERR_INTERNAL_ERROR","ERR_RESTRICTED_MODE_CAP_REACHED","ERR_ROOMS_LIMIT_REACHED","ERR_INVALID_SCHEMA","ERR_INVALID_ROOM_LIMIT","ERR_INVALID_MAX_ENTITIES","ERR_ROOM_NOT_FOUND","ERR_HIGH_MEMORY_PRESSURE"]},"user_message":{"description":"User-friendly error message.","type":"string"}},"required":["error_code","user_message"]}}},"paths":{"/get":{"get":{"tags":["rooms"],"summary":"Fetches the list of rooms on the server.","parameters":[{"name":"include_player_ids","in":"query","required":false,"description":"Whether to include connected player IDs in the response.","schema":{"type":"boolean"}}],"responses":{"200":{"description":"List of rooms was fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rooms.GetRoomsResponse"}}}},"500":{"description":"Internal Replication Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## POST /kv

> Sets the Key-Value (KVP) data for a room instance.

```json
{"openapi":"3.0.4","info":{"title":"Replication Server REST API","version":"v8.0.0"},"tags":[{"name":"rooms","description":"Rooms related operations"}],"servers":[{"url":"http://127.0.0.1:64001","description":"Local Rooms Replication Server"},{"url":"http://127.0.0.1:32004","description":"Local World Replication Server"}],"security":[{"rs_auth":[]}],"components":{"securitySchemes":{"rs_auth":{"type":"http","scheme":"bearer"}},"schemas":{"rooms.KVPRequest":{"type":"object","properties":{"RoomID":{"description":"ID of the room instance as assigned by the server.","type":"integer","format":"uint16","minimum":1,"maximum":65535},"Data":{"description":"Key-Value Pair (KVP) data for the room instance. Replaces the room's current\ndata; it is not merged into it. Keys are at most 128 characters.","type":"object","maxProperties":128,"additionalProperties":{"type":"string","maxLength":128}}},"required":["RoomID","Data"]},"rooms.KVPResponse":{"type":"object","properties":{"RoomID":{"description":"ID of the room instance as assigned by the server.","type":"integer","format":"uint16","minimum":1,"maximum":65535}},"required":["RoomID"]},"Error":{"type":"object","properties":{"error_code":{"description":"Error code indicating the type of error that occurred.","type":"string","enum":["ERR_BAD_REQUEST","ERR_INTERNAL_ERROR","ERR_RESTRICTED_MODE_CAP_REACHED","ERR_ROOMS_LIMIT_REACHED","ERR_INVALID_SCHEMA","ERR_INVALID_ROOM_LIMIT","ERR_INVALID_MAX_ENTITIES","ERR_ROOM_NOT_FOUND","ERR_HIGH_MEMORY_PRESSURE"]},"user_message":{"description":"User-friendly error message.","type":"string"}},"required":["error_code","user_message"]}}},"paths":{"/kv":{"post":{"tags":["rooms"],"summary":"Sets the Key-Value (KVP) data for a room instance.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/rooms.KVPRequest"}}},"required":true},"responses":{"200":{"description":"KVP data was set successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rooms.KVPResponse"}}}},"400":{"description":"Bad request; invalid room ID or metadata limits exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Room to set KVP data for was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Replication Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Sets the Private Key-Value Pair (KVP) data for a room instance.

> Private KVP data is reported back through \`/get\` and allows longer values than the\
> public KVP data.

```json
{"openapi":"3.0.4","info":{"title":"Replication Server REST API","version":"v8.0.0"},"tags":[{"name":"rooms","description":"Rooms related operations"}],"servers":[{"url":"http://127.0.0.1:64001","description":"Local Rooms Replication Server"},{"url":"http://127.0.0.1:32004","description":"Local World Replication Server"}],"security":[{"rs_auth":[]}],"components":{"securitySchemes":{"rs_auth":{"type":"http","scheme":"bearer"}},"schemas":{"rooms.PrivateKVPRequest":{"type":"object","properties":{"RoomID":{"description":"ID of the room instance as assigned by the server.","type":"integer","format":"uint16","minimum":1,"maximum":65535},"Data":{"description":"Private Key-Value Pair (KVP) data for the room instance. Replaces the room's\ncurrent data; it is not merged into it. Keys are at most 128 characters.","type":"object","maxProperties":128,"additionalProperties":{"type":"string","maxLength":1024}}},"required":["RoomID","Data"]},"rooms.KVPResponse":{"type":"object","properties":{"RoomID":{"description":"ID of the room instance as assigned by the server.","type":"integer","format":"uint16","minimum":1,"maximum":65535}},"required":["RoomID"]},"Error":{"type":"object","properties":{"error_code":{"description":"Error code indicating the type of error that occurred.","type":"string","enum":["ERR_BAD_REQUEST","ERR_INTERNAL_ERROR","ERR_RESTRICTED_MODE_CAP_REACHED","ERR_ROOMS_LIMIT_REACHED","ERR_INVALID_SCHEMA","ERR_INVALID_ROOM_LIMIT","ERR_INVALID_MAX_ENTITIES","ERR_ROOM_NOT_FOUND","ERR_HIGH_MEMORY_PRESSURE"]},"user_message":{"description":"User-friendly error message.","type":"string"}},"required":["error_code","user_message"]}}},"paths":{"/pkv":{"post":{"tags":["rooms"],"summary":"Sets the Private Key-Value Pair (KVP) data for a room instance.","description":"Private KVP data is reported back through `/get` and allows longer values than the\npublic KVP data.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/rooms.PrivateKVPRequest"}}},"required":true},"responses":{"200":{"description":"Private KVP data was set successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rooms.KVPResponse"}}}},"400":{"description":"Bad request; invalid room ID or metadata limits exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Room to set Private KVP data for was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Replication Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## POST /tags

> Sets the tags for a room instance.

```json
{"openapi":"3.0.4","info":{"title":"Replication Server REST API","version":"v8.0.0"},"tags":[{"name":"rooms","description":"Rooms related operations"}],"servers":[{"url":"http://127.0.0.1:64001","description":"Local Rooms Replication Server"},{"url":"http://127.0.0.1:32004","description":"Local World Replication Server"}],"security":[{"rs_auth":[]}],"components":{"securitySchemes":{"rs_auth":{"type":"http","scheme":"bearer"}},"schemas":{"rooms.TagRequest":{"type":"object","properties":{"RoomID":{"description":"ID of the room instance as assigned by the server.","type":"integer","format":"uint16","minimum":1,"maximum":65535},"Tags":{"description":"Tags for the room instance. Replaces the room's current tags; they are not\nmerged into them.","type":"array","items":{"type":"string","maxLength":128},"maxItems":128}},"required":["RoomID","Tags"]},"rooms.TagResponse":{"type":"object","properties":{"RoomID":{"description":"ID of the room instance as assigned by the server.","type":"integer","format":"uint16","minimum":1,"maximum":65535}},"required":["RoomID"]},"Error":{"type":"object","properties":{"error_code":{"description":"Error code indicating the type of error that occurred.","type":"string","enum":["ERR_BAD_REQUEST","ERR_INTERNAL_ERROR","ERR_RESTRICTED_MODE_CAP_REACHED","ERR_ROOMS_LIMIT_REACHED","ERR_INVALID_SCHEMA","ERR_INVALID_ROOM_LIMIT","ERR_INVALID_MAX_ENTITIES","ERR_ROOM_NOT_FOUND","ERR_HIGH_MEMORY_PRESSURE"]},"user_message":{"description":"User-friendly error message.","type":"string"}},"required":["error_code","user_message"]}}},"paths":{"/tags":{"post":{"tags":["rooms"],"summary":"Sets the tags for a room instance.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/rooms.TagRequest"}}},"required":true},"responses":{"200":{"description":"Tags were set successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rooms.TagResponse"}}}},"400":{"description":"Bad request; invalid room ID or metadata limits exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Room to set tags for was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Replication Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Checks whether a schema is loaded on the server.

> Returns no body. Tells the caller whether the schema has to be uploaded with the\
> next \`/add\` call.

```json
{"openapi":"3.0.4","info":{"title":"Replication Server REST API","version":"v8.0.0"},"tags":[{"name":"rooms","description":"Rooms related operations"}],"servers":[{"url":"http://127.0.0.1:64001","description":"Local Rooms Replication Server"},{"url":"http://127.0.0.1:32004","description":"Local World Replication Server"}],"security":[{"rs_auth":[]}],"components":{"securitySchemes":{"rs_auth":{"type":"http","scheme":"bearer"}}},"paths":{"/schemas/{schemaID}":{"head":{"tags":["rooms"],"summary":"Checks whether a schema is loaded on the server.","description":"Returns no body. Tells the caller whether the schema has to be uploaded with the\nnext `/add` call.","parameters":[{"name":"schemaID","in":"path","required":true,"description":"Hash of the schema to look for.","schema":{"type":"string"}}],"responses":{"200":{"description":"The schema is loaded on the server"},"404":{"description":"The schema is not loaded on the server"}}}}}}
```