> 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.3/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":"v7.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.","type":"object","additionalProperties":{"type":"string"}},"PrivateKVP":{"description":"Private Key-Value Pair (KVP) data associated with the room instance.","type":"object","additionalProperties":{"type":"string"}},"Tags":{"description":"Tags associated with the room instance.","type":"array","items":{"type":"string"}},"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":"v7.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":"v7.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},"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.","type":"object","additionalProperties":{"type":"string"}},"PrivateKVP":{"description":"Private Key-Value Pair (KVP) data associated with the room instance.","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.","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":"v7.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 to be set for the room instance.","type":"object","maxItems":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":{"/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"}}}},"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"}}}}}}}}}
```

## POST /pkv

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

```json
{"openapi":"3.0.4","info":{"title":"Replication Server REST API","version":"v7.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 to be set for the room instance.","type":"object","maxItems":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.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/rooms.KVPRequest"}}},"required":true},"responses":{"200":{"description":"Private KVP data was set successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rooms.KVPResponse"}}}},"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":"v7.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 to be set for the room instance.","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"}}}},"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"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.coherence.io/2.3/hosting/self-hosting/open-api-reference/rooms.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.