# 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"}}}}}}}}}
```