{ "openapi": "3.0.3", "info": { "title": "VSee Clinic Rooms API", "description": "The VSee Clinic Rooms API allows developers to manage video consultation rooms within the VSee Clinic platform.\n\n## Room Codes\n\nEvery room has a unique `code` (e.g., `my-room-123`). The room code is used to identify the room in API calls (e.g., `PUT /rooms/{code}`) and to construct the room URL for joining: `https://{account_code}.vsee.me/{room_code}`.\n\nWhen creating a room, you can optionally specify a `code`. If omitted, the system generates one automatically. Room codes must be unique within your clinic.\n\n## Authentication\n\nReading rooms (`GET /rooms`, `GET /rooms/{code}`) requires only the `X-AccountCode` header. Creating, updating, or deleting rooms requires the **Clinic Admin API Token** in the `X-ApiToken` header \u2014 not a user session token.\n", "version": "3.0", "contact": { "email": "admin@vsee.com" } }, "x-readme": { "explorer-enabled": false, "proxy-enabled": false, "samples-languages": [ "curl", "python", "javascript", "java" ] }, "servers": [ { "url": "https://api.vseepreview.com/api_v3", "description": "Staging" } ], "paths": { "/rooms": { "get": { "tags": [ "Rooms" ], "summary": "List rooms", "description": "Retrieve a list of rooms with pagination. This is a public endpoint.\n\n**Note:** The Rooms API supports the DataTable API format for server-side pagination and filtering.", "operationId": "listRooms", "parameters": [ { "name": "X-AccountCode", "in": "header", "description": "Account code", "required": true, "schema": { "type": "string" }, "example": "vclinic" }, { "name": "page", "in": "query", "description": "Page number for pagination", "schema": { "type": "integer" }, "example": 1 }, { "name": "limit", "in": "query", "description": "Number of records per page", "schema": { "type": "integer" }, "example": 10 } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RoomSummary" } } } }, "examples": { "success": { "summary": "List of rooms", "value": { "data": [ { "slug": "room1", "name": "Room 1", "domain": "demo.vsee.me", "code": "room1_code", "created": 1427922788, "modified": 1427922788 }, { "slug": "room2", "name": "Room 2", "domain": "demo.vsee.me", "code": "room2_code", "created": 1427922800, "modified": 1427922800 } ] } } } } } } }, "x-auth-type": "account-code-only" }, "post": { "tags": [ "Rooms" ], "summary": "Create room", "description": "Create a new room for video consultations.", "operationId": "createRoom", "parameters": [ { "name": "X-ApiToken", "in": "header", "description": "API token", "required": true, "schema": { "type": "string" }, "example": "your_api_token" }, { "name": "X-AccountCode", "in": "header", "description": "Account code", "required": true, "schema": { "type": "string" }, "example": "vclinic" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain", "name" ], "properties": { "domain": { "type": "string", "description": "Clinic's domain", "example": "vclinic.vsee.me" }, "code": { "type": "string", "description": "Room code (optional, should be unique)", "example": "b4vjj" }, "slug": { "type": "string", "description": "Room slug (optional)", "example": "provider00102" }, "name": { "type": "string", "description": "Room's name", "example": "provider00102 room" } } } } } }, "responses": { "200": { "description": "Room created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RoomDetail" } } }, "examples": { "success": { "summary": "Room created", "value": { "data": { "visits": { "walkin": { "enabled": true }, "appointment": { "enabled": false } }, "auth": { "guest": { "type": 600, "log_in": { "enabled": true } } }, "subtitle": "If this is an emergency, please call 911.", "slug": "provider00102", "name": "provider00102 room", "domain": "vclinic.vsee.me", "active": true, "users": "85741", "account_code": "clinic", "provider_ids": [ "85741" ], "public_access_room": true, "modified": 1605728974, "created": 1605728974, "payment": { "consultations": [ { "id": "5fb57ace-4808-4346-ad3c-3348925862c1", "description": "15-min Consultation", "duration": 15, "amount": 0, "group": false, "charge": false, "slots": 1 } ], "currency": "USD" }, "operation_settings": { "is_closed": false, "close_msg": "Service currently not available. Please check back later", "default_timezone": "America/Los_Angeles" }, "id": "171", "code": "b4vjj" } } } } } } }, "400": { "description": "Room already exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } } }, "examples": { "room_exists": { "summary": "Room already exists", "value": { "code": 400, "message": "In domain 'vclinic.vsee.me' slug 'uat2' already exists." } } } } } } }, "x-auth-type": "admin-token" } }, "/rooms/{code}": { "get": { "tags": [ "Rooms" ], "summary": "Get room details", "description": "Retrieve detailed information about a specific room. This is a public endpoint.", "operationId": "getRoom", "parameters": [ { "name": "X-AccountCode", "in": "header", "description": "Account code", "required": true, "schema": { "type": "string" }, "example": "vclinic" }, { "name": "code", "in": "path", "required": true, "description": "Room code", "schema": { "type": "string" }, "example": "room1" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RoomDetail" } } }, "examples": { "success": { "summary": "Room details", "value": { "data": { "description": "", "specialties": [ { "code": "general_care", "name": "Default", "duration": 15 }, { "code": "primary_care", "name": "Primary Care", "duration": 15 }, { "code": "psychiatry", "name": "Psychiatry", "duration": 30 }, { "code": "dermatology", "name": "Dermatology", "duration": 15 } ], "modified": 1466796316, "created": 1446802721, "payment": { "paymentCurrency": "USD", "consultations": [ { "description": "15-min Consultation", "amount": 0, "duration": 15 }, { "description": "30 min", "amount": 20, "duration": 30 }, { "description": "45 min", "amount": 40, "duration": 45 } ] }, "slug": "room1", "name": "Room 1", "domain": "demo.vsee.me", "code": "room1", "account_code": "DEMO-ACCOUNT", "operation_settings": { "close_message": { "html": "" }, "close_msg": "", "closed_days": [ "saturday" ], "default_timezone": "America/Los_Angeles", "is_closed": false, "is_closed_now": false, "is_open_all_time": false, "is_scheduled_closed": false } } } } } } } } }, "x-auth-type": "account-code-only" } }, "/rooms/{code}/providers": { "get": { "tags": [ "Room Providers" ], "summary": "List room providers", "description": "Retrieve a list of providers associated with a specific room. This is a public endpoint.", "operationId": "listRoomProviders", "parameters": [ { "name": "X-AccountCode", "in": "header", "description": "Account code", "required": true, "schema": { "type": "string" }, "example": "vclinic" }, { "name": "code", "in": "path", "required": true, "description": "Room code", "schema": { "type": "string" }, "example": "example-room-code" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Provider" } } } }, "examples": { "success": { "summary": "List of room providers", "value": { "data": [ { "id": "401", "username": "provider-401", "code": "", "subtype": "482", "first_name": "Jarod", "last_name": "Sun 401", "vseeid": "evisitdev+user401", "photo": null, "title": "", "suffix": "", "status": false, "short_bio": false } ] } } } } } } }, "x-auth-type": "account-code-only" } }, "/rooms/{code}/providers/{id}": { "get": { "tags": [ "Room Providers" ], "summary": "Get room provider detail", "description": "Retrieve detailed information about a specific provider in a room. This is a public endpoint.", "operationId": "getRoomProvider", "parameters": [ { "name": "X-AccountCode", "in": "header", "description": "Account code", "required": true, "schema": { "type": "string" }, "example": "vclinic" }, { "name": "code", "in": "path", "required": true, "description": "Room code", "schema": { "type": "string" }, "example": "ceproom1" }, { "name": "id", "in": "path", "required": true, "description": "Provider ID", "schema": { "type": "string" }, "example": "826" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProviderDetail" } } }, "examples": { "success": { "summary": "Provider details", "value": { "data": { "id": "826", "code": "55de45a2ce384a24ad633301ac1f0144", "first_name": "John", "last_name": "Will", "username": "provider1", "vseeid": "conciergedev+user826", "email": "anton+provider1@vsee.com", "active": true, "title": "Dr.", "suffix": "M.D.", "tos": false, "phone": "334 2222211", "subtype": "482", "status": false, "educational_training": "edu and training...", "professional_interests": "interests...", "personal_interests": "some personal hobby", "short_bio": "..." } } } } } } } }, "x-auth-type": "account-code-only" } }, "/rooms/{code}/queue": { "get": { "tags": [ "Room Queue" ], "summary": "Get room queue info", "description": "Retrieve queue information for a specific room. The waiting time is calculated as average_visit_time * before_me. This is a public endpoint.", "operationId": "getRoomQueue", "parameters": [ { "name": "X-AccountCode", "in": "header", "description": "Account code", "required": true, "schema": { "type": "string" }, "example": "vclinic" }, { "name": "code", "in": "path", "required": true, "description": "Room code", "schema": { "type": "string" }, "example": "ceproom1" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/QueueInfo" } } }, "examples": { "success": { "summary": "Room queue information", "value": { "data": { "length": 10, "capacity": 100, "average_visit_time": 3600, "before_me": 3 } } } } } } } }, "x-auth-type": "account-code-only" } }, "/users/{id}/rooms": { "post": { "tags": [ "User Rooms" ], "summary": "Associate room to user", "description": "Associate a room with a user.", "operationId": "associateRoomToUser", "parameters": [ { "name": "X-ApiToken", "in": "header", "description": "API token", "required": true, "schema": { "type": "string" }, "example": "your_api_token" }, { "name": "X-AccountCode", "in": "header", "description": "Account code", "required": true, "schema": { "type": "string" }, "example": "vclinic" }, { "name": "id", "in": "path", "required": true, "description": "User ID", "schema": { "type": "string" }, "example": "85741" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "description": "Room code", "example": "b4vjj" }, "default": { "type": "boolean", "description": "Set this room as default (optional)", "example": false } } } } } }, "responses": { "200": { "description": "Room associated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UserRoom" } } } }, "examples": { "success": { "summary": "Room associated to user", "value": { "data": [ { "_id": "171", "slug": "provider00102", "name": "provider00102 room", "domain": "clinic.vseepreview.com", "code": "b4vjj", "active": true, "users": "85741", "account_code": "clinic", "provider_ids": [ "85741" ], "public_access_room": true, "modified": { "sec": 1605728974, "usec": 177000 }, "created": { "sec": 1605728974, "usec": 177000 }, "payment": { "consultations": [ { "id": "5fb57ace-4808-4346-ad3c-3348925862c1", "description": "15-min Consultation", "duration": 15, "amount": 0, "group": false, "charge": false, "slots": 1 } ] }, "default": false } ] } } } } } } }, "x-auth-type": "admin-token" } }, "/users/{id}/rooms/{room_code}": { "delete": { "tags": [ "User Rooms" ], "summary": "Remove room from user", "description": "Remove a room association from a user.", "operationId": "removeRoomFromUser", "parameters": [ { "name": "X-ApiToken", "in": "header", "description": "API token", "required": true, "schema": { "type": "string" }, "example": "your_api_token" }, { "name": "X-AccountCode", "in": "header", "description": "Account code", "required": true, "schema": { "type": "string" }, "example": "vclinic" }, { "name": "id", "in": "path", "required": true, "description": "User ID", "schema": { "type": "string" }, "example": "85741" }, { "name": "room_code", "in": "path", "required": true, "description": "Room code", "schema": { "type": "string" }, "example": "b4vjj" } ], "responses": { "200": { "description": "Room removed successfully", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "success": { "summary": "Room removed", "value": {} } } } } } }, "x-auth-type": "admin-token" } } }, "components": { "schemas": { "RoomSummary": { "type": "object", "properties": { "slug": { "type": "string", "example": "room1" }, "name": { "type": "string", "example": "Room 1" }, "domain": { "type": "string", "example": "demo.vsee.me" }, "code": { "type": "string", "example": "room1_code" }, "created": { "type": "integer", "example": 1427922788 }, "modified": { "type": "integer", "example": 1427922788 } } }, "RoomDetail": { "type": "object", "properties": { "id": { "type": "string", "example": "171" }, "code": { "type": "string", "example": "b4vjj" }, "slug": { "type": "string", "example": "room1" }, "name": { "type": "string", "example": "Room 1" }, "domain": { "type": "string", "example": "demo.vsee.me" }, "account_code": { "type": "string", "example": "DEMO-ACCOUNT" }, "description": { "type": "string", "example": "" }, "active": { "type": "boolean", "example": true }, "public_access_room": { "type": "boolean", "example": true }, "created": { "type": "integer", "example": 1446802721 }, "modified": { "type": "integer", "example": 1466796316 }, "visits": { "type": "object", "properties": { "walkin": { "type": "object", "properties": { "enabled": { "type": "boolean", "example": true } } }, "appointment": { "type": "object", "properties": { "enabled": { "type": "boolean", "example": false } } } } }, "payment": { "type": "object", "properties": { "currency": { "type": "string", "example": "USD" }, "paymentCurrency": { "type": "string", "example": "USD" }, "consultations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "description": { "type": "string" }, "duration": { "type": "integer" }, "amount": { "type": "number" }, "group": { "type": "boolean" }, "charge": { "type": "boolean" }, "slots": { "type": "integer" } } } } } }, "specialties": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "duration": { "type": "integer" } } } }, "operation_settings": { "type": "object", "properties": { "is_closed": { "type": "boolean" }, "close_msg": { "type": "string" }, "default_timezone": { "type": "string" }, "closed_days": { "type": "array", "items": { "type": "string" } } } }, "provider_ids": { "type": "array", "items": { "type": "string" } } } }, "Provider": { "type": "object", "properties": { "id": { "type": "string", "example": "401" }, "username": { "type": "string", "example": "provider-401" }, "code": { "type": "string", "example": "" }, "subtype": { "type": "string", "example": "482" }, "first_name": { "type": "string", "example": "Jarod" }, "last_name": { "type": "string", "example": "Sun 401" }, "vseeid": { "type": "string", "example": "evisitdev+user401" }, "photo": { "type": "string", "nullable": true }, "title": { "type": "string", "example": "" }, "suffix": { "type": "string", "example": "" }, "status": { "type": "boolean", "example": false }, "short_bio": { "type": "boolean", "example": false } } }, "ProviderDetail": { "type": "object", "properties": { "id": { "type": "string", "example": "826" }, "code": { "type": "string", "example": "55de45a2ce384a24ad633301ac1f0144" }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Will" }, "username": { "type": "string", "example": "provider1" }, "vseeid": { "type": "string", "example": "conciergedev+user826" }, "email": { "type": "string", "example": "anton+provider1@vsee.com" }, "active": { "type": "boolean", "example": true }, "title": { "type": "string", "example": "Dr." }, "suffix": { "type": "string", "example": "M.D." }, "tos": { "type": "boolean", "example": false }, "phone": { "type": "string", "example": "334 2222211" }, "subtype": { "type": "string", "example": "482" }, "status": { "type": "boolean", "example": false }, "educational_training": { "type": "string", "example": "edu and training..." }, "professional_interests": { "type": "string", "example": "interests..." }, "personal_interests": { "type": "string", "example": "some personal hobby" }, "short_bio": { "type": "string", "example": "..." } } }, "QueueInfo": { "type": "object", "properties": { "length": { "type": "integer", "description": "Total current queue length", "example": 10 }, "capacity": { "type": "integer", "description": "Maximum possible queue length", "example": 100 }, "average_visit_time": { "type": "integer", "description": "Average time in seconds per patient", "example": 3600 }, "before_me": { "type": "integer", "description": "Number of patients in the queue before the current user", "example": 3 } } }, "UserRoom": { "type": "object", "properties": { "_id": { "type": "string", "example": "171" }, "slug": { "type": "string", "example": "provider00102" }, "name": { "type": "string", "example": "provider00102 room" }, "domain": { "type": "string", "example": "clinic.vseepreview.com" }, "code": { "type": "string", "example": "b4vjj" }, "active": { "type": "boolean", "example": true }, "users": { "type": "string", "example": "85741" }, "account_code": { "type": "string", "example": "clinic" }, "provider_ids": { "type": "array", "items": { "type": "string" }, "example": [ "85741" ] }, "public_access_room": { "type": "boolean", "example": true }, "modified": { "type": "object", "properties": { "sec": { "type": "integer" }, "usec": { "type": "integer" } } }, "created": { "type": "object", "properties": { "sec": { "type": "integer" }, "usec": { "type": "integer" } } }, "payment": { "type": "object", "properties": { "consultations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "description": { "type": "string" }, "duration": { "type": "integer" }, "amount": { "type": "number" }, "group": { "type": "boolean" }, "charge": { "type": "boolean" }, "slots": { "type": "integer" } } } } } }, "default": { "type": "boolean", "example": false } } } } } }