# Rooms API

## Autorización

Todos los endpoints descritos a continuación utilizan la cabecera `Authorization` con esquema Bearer.

Un API token lo puedes obtener desde nuestro dashboard. Este deberá ser de tipo `api-token` el cual es el único permitido para VPaaS.

{% hint style="info" %}
Si estás en ambiente de desarrollo, te recomendamos crear un token sin lista blanca de IPs; esto evitará problemas de bloqueos por IP dinámica.
{% endhint %}

Obtiene tus API Tokens directamente desde nuestra terminal de desarrollador:

{% @videsk-iframe/videsk-iframe url="<https://forge.videsk.io/dev-terminal>" %}

***

## List rooms

> Retrieve a paginated list of rooms for the authenticated account

```json
{"openapi":"3.0.3","info":{"title":"VPaaS Rooms API","version":"1.0.0"},"servers":[{"url":"https://api.videsk.io","description":"Production server"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token authentication using API token"}},"schemas":{"RoomsList":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of rooms"},"limit":{"type":"integer","description":"Number of rooms per page"},"skip":{"type":"integer","description":"Number of rooms skipped"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Room"}}}},"Room":{"type":"object","properties":{"id":{"type":"string","format":"objectid","description":"Unique room identifier"},"name":{"type":"string","maxLength":500,"description":"Internal name of the room"},"externalId":{"type":"string","maxLength":100,"description":"External identifier for the room"},"exp":{"type":"string","format":"date-time","description":"Expiration date (must be in the future)"},"nbf":{"type":"string","format":"date-time","description":"Not before date (when room becomes active)"},"authorizations":{"type":"array","items":{"$ref":"#/components/schemas/Authorization"},"description":"List of authorized access attempts"}},"required":["id","name","externalId","exp","nbf","authorizations"]},"Authorization":{"type":"object","properties":{"ip":{"type":"string","description":"IP address of the client"},"jti":{"type":"string","description":"JWT ID for the authorization token"},"createdAt":{"type":"string","format":"date-time","description":"Authorization creation timestamp"}},"required":["ip","jti","createdAt"],"additionalProperties":false},"Error":{"type":"object","properties":{"name":{"type":"string","description":"Error type name"},"message":{"type":"string","description":"Error message"},"code":{"type":"integer","description":"HTTP status code"},"className":{"type":"string","description":"Error class name"},"data":{"type":"object","description":"Additional error data"},"errors":{"type":"object","description":"Validation errors (if applicable)"}},"required":["name","message","code"]}}},"paths":{"/vpaas/rooms":{"get":{"summary":"List rooms","description":"Retrieve a paginated list of rooms for the authenticated account","tags":["Rooms"],"parameters":[{"name":"$limit","in":"query","description":"Maximum number of results to return","schema":{"type":"integer","minimum":1,"maximum":100,"default":10}},{"name":"$skip","in":"query","description":"Number of results to skip","schema":{"type":"integer","minimum":0,"default":0}},{"name":"$sort","in":"query","description":"Sort order (field:1 for asc, field:-1 for desc)","schema":{"type":"object"},"style":"deepObject","explode":true},{"name":"ended","in":"query","description":"Filter by ended status","schema":{"type":"boolean"}},{"name":"externalId","in":"query","description":"Filter by external ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoomsList"}}}},"401":{"description":"Unauthorized - Invalid or missing API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Create a new room

> Create a new video room with optional configuration

```json
{"openapi":"3.0.3","info":{"title":"VPaaS Rooms API","version":"1.0.0"},"servers":[{"url":"https://api.videsk.io","description":"Production server"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token authentication using API token"}},"schemas":{"CreateRoomRequest":{"type":"object","properties":{"externalId":{"type":"string","maxLength":100,"description":"External identifier (auto-generated if not provided)"},"name":{"type":"string","maxLength":500,"description":"Internal room name (auto-generated if not provided)"},"exp":{"type":"string","format":"date-time","description":"Expiration date (defaults to +3 hours if not provided)"},"nbf":{"type":"string","format":"date-time","description":"Not before date (defaults to now if not provided)"},"settings":{"type":"object","description":"Room configuration settings"}},"additionalProperties":false},"CreateRoomResponse":{"allOf":[{"$ref":"#/components/schemas/Room"},{"type":"object","properties":{"accessToken":{"type":"string","description":"JWT access token for the room"}},"required":["accessToken"]}]},"Room":{"type":"object","properties":{"id":{"type":"string","format":"objectid","description":"Unique room identifier"},"name":{"type":"string","maxLength":500,"description":"Internal name of the room"},"externalId":{"type":"string","maxLength":100,"description":"External identifier for the room"},"exp":{"type":"string","format":"date-time","description":"Expiration date (must be in the future)"},"nbf":{"type":"string","format":"date-time","description":"Not before date (when room becomes active)"},"authorizations":{"type":"array","items":{"$ref":"#/components/schemas/Authorization"},"description":"List of authorized access attempts"}},"required":["id","name","externalId","exp","nbf","authorizations"]},"Authorization":{"type":"object","properties":{"ip":{"type":"string","description":"IP address of the client"},"jti":{"type":"string","description":"JWT ID for the authorization token"},"createdAt":{"type":"string","format":"date-time","description":"Authorization creation timestamp"}},"required":["ip","jti","createdAt"],"additionalProperties":false},"Error":{"type":"object","properties":{"name":{"type":"string","description":"Error type name"},"message":{"type":"string","description":"Error message"},"code":{"type":"integer","description":"HTTP status code"},"className":{"type":"string","description":"Error class name"},"data":{"type":"object","description":"Additional error data"},"errors":{"type":"object","description":"Validation errors (if applicable)"}},"required":["name","message","code"]}}},"paths":{"/vpaas/rooms":{"post":{"summary":"Create a new room","description":"Create a new video room with optional configuration","tags":["Rooms"],"parameters":[{"name":"Content-Type","in":"header","required":true,"description":"Content type must be application/json","schema":{"type":"string","enum":["application/json"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRoomRequest"}}}},"responses":{"201":{"description":"Room created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRoomResponse"}}}},"400":{"description":"Bad request - Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict - externalId already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Get room by ID

> Retrieve a specific room by its ID or externalId

```json
{"openapi":"3.0.3","info":{"title":"VPaaS Rooms API","version":"1.0.0"},"servers":[{"url":"https://api.videsk.io","description":"Production server"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token authentication using API token"}},"schemas":{"Room":{"type":"object","properties":{"id":{"type":"string","format":"objectid","description":"Unique room identifier"},"name":{"type":"string","maxLength":500,"description":"Internal name of the room"},"externalId":{"type":"string","maxLength":100,"description":"External identifier for the room"},"exp":{"type":"string","format":"date-time","description":"Expiration date (must be in the future)"},"nbf":{"type":"string","format":"date-time","description":"Not before date (when room becomes active)"},"authorizations":{"type":"array","items":{"$ref":"#/components/schemas/Authorization"},"description":"List of authorized access attempts"}},"required":["id","name","externalId","exp","nbf","authorizations"]},"Authorization":{"type":"object","properties":{"ip":{"type":"string","description":"IP address of the client"},"jti":{"type":"string","description":"JWT ID for the authorization token"},"createdAt":{"type":"string","format":"date-time","description":"Authorization creation timestamp"}},"required":["ip","jti","createdAt"],"additionalProperties":false},"Error":{"type":"object","properties":{"name":{"type":"string","description":"Error type name"},"message":{"type":"string","description":"Error message"},"code":{"type":"integer","description":"HTTP status code"},"className":{"type":"string","description":"Error class name"},"data":{"type":"object","description":"Additional error data"},"errors":{"type":"object","description":"Validation errors (if applicable)"}},"required":["name","message","code"]}}},"paths":{"/vpaas/rooms/{roomId}":{"get":{"summary":"Get room by ID","description":"Retrieve a specific room by its ID or externalId","tags":["Rooms"],"parameters":[{"name":"roomId","in":"path","required":true,"description":"Room ID (ObjectId) or external ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Room found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Room"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Room not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Delete room (Not allowed)

> Room deletion is not permitted through the API

```json
{"openapi":"3.0.3","info":{"title":"VPaaS Rooms API","version":"1.0.0"},"servers":[{"url":"https://api.videsk.io","description":"Production server"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token authentication using API token"}},"schemas":{"Error":{"type":"object","properties":{"name":{"type":"string","description":"Error type name"},"message":{"type":"string","description":"Error message"},"code":{"type":"integer","description":"HTTP status code"},"className":{"type":"string","description":"Error class name"},"data":{"type":"object","description":"Additional error data"},"errors":{"type":"object","description":"Validation errors (if applicable)"}},"required":["name","message","code"]}}},"paths":{"/vpaas/rooms/{roomId}":{"delete":{"summary":"Delete room (Not allowed)","description":"Room deletion is not permitted through the API","tags":["Rooms"],"parameters":[{"name":"roomId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"403":{"description":"Forbidden - Room deletion not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Update room

> Update room properties like expiration, name, or end status. Can optionally generate new access token.

```json
{"openapi":"3.0.3","info":{"title":"VPaaS Rooms API","version":"1.0.0"},"servers":[{"url":"https://api.videsk.io","description":"Production server"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token authentication using API token"}},"schemas":{"UpdateRoomRequest":{"type":"object","properties":{"generateToken":{"type":"boolean","default":false,"description":"Whether to generate a new access token"},"exp":{"type":"string","format":"date-time","description":"New expiration date"},"nbf":{"type":"string","format":"date-time","description":"New not before date"},"ended":{"type":"boolean","description":"Mark room as ended"},"name":{"type":"string","maxLength":500,"description":"New room name"}},"additionalProperties":false},"UpdateRoomResponse":{"allOf":[{"$ref":"#/components/schemas/Room"},{"type":"object","properties":{"accessToken":{"type":"string","description":"JWT access token (only if generateToken was true)"}}}]},"Room":{"type":"object","properties":{"id":{"type":"string","format":"objectid","description":"Unique room identifier"},"name":{"type":"string","maxLength":500,"description":"Internal name of the room"},"externalId":{"type":"string","maxLength":100,"description":"External identifier for the room"},"exp":{"type":"string","format":"date-time","description":"Expiration date (must be in the future)"},"nbf":{"type":"string","format":"date-time","description":"Not before date (when room becomes active)"},"authorizations":{"type":"array","items":{"$ref":"#/components/schemas/Authorization"},"description":"List of authorized access attempts"}},"required":["id","name","externalId","exp","nbf","authorizations"]},"Authorization":{"type":"object","properties":{"ip":{"type":"string","description":"IP address of the client"},"jti":{"type":"string","description":"JWT ID for the authorization token"},"createdAt":{"type":"string","format":"date-time","description":"Authorization creation timestamp"}},"required":["ip","jti","createdAt"],"additionalProperties":false},"Error":{"type":"object","properties":{"name":{"type":"string","description":"Error type name"},"message":{"type":"string","description":"Error message"},"code":{"type":"integer","description":"HTTP status code"},"className":{"type":"string","description":"Error class name"},"data":{"type":"object","description":"Additional error data"},"errors":{"type":"object","description":"Validation errors (if applicable)"}},"required":["name","message","code"]}}},"paths":{"/vpaas/rooms/{roomId}":{"patch":{"summary":"Update room","description":"Update room properties like expiration, name, or end status. Can optionally generate new access token.","tags":["Rooms"],"parameters":[{"name":"roomId","in":"path","required":true,"description":"Room ID (ObjectId) or external ID","schema":{"type":"string"}},{"name":"Content-Type","in":"header","required":true,"description":"Content type must be application/json","schema":{"type":"string","enum":["application/json"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateRoomRequest"}}}},"responses":{"200":{"description":"Room updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateRoomResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Room not found or already ended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Join a room

> Generate access token to join an existing room

```json
{"openapi":"3.0.3","info":{"title":"VPaaS Rooms API","version":"1.0.0"},"servers":[{"url":"https://api.videsk.io","description":"Production server"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token authentication using API token"}},"schemas":{"JoinRoomResponse":{"type":"object","properties":{"accessToken":{"type":"string","description":"JWT access token for joining the room"}},"required":["accessToken"]},"Error":{"type":"object","properties":{"name":{"type":"string","description":"Error type name"},"message":{"type":"string","description":"Error message"},"code":{"type":"integer","description":"HTTP status code"},"className":{"type":"string","description":"Error class name"},"data":{"type":"object","description":"Additional error data"},"errors":{"type":"object","description":"Validation errors (if applicable)"}},"required":["name","message","code"]}}},"paths":{"/vpaas/rooms/{roomId}/join":{"post":{"summary":"Join a room","description":"Generate access token to join an existing room","tags":["Rooms"],"parameters":[{"name":"roomId","in":"path","required":true,"description":"Room ID (ObjectId) or external ID to join","schema":{"type":"string"}},{"name":"Content-Type","in":"header","required":true,"description":"Content type must be application/json","schema":{"type":"string","enum":["application/json"]}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","description":"Optional request body (currently no additional parameters required)","additionalProperties":false}}}},"responses":{"200":{"description":"Successfully joined room","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JoinRoomResponse"}}}},"400":{"description":"Bad request - Missing room ID or invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```


---

# Agent Instructions: 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.videsk.io/es-developers/vpaas/rooms-api.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.