Vircadia World API

The World API Manager is the interface between clients and the PostgreSQL database, and any other services that might be utilized.

REST API

The REST API is accessible at the base path:

/world/rest

Available Endpoints

Endpoint	Method	Path	Description
AUTH_SESSION_VALIDATE	POST	/world/rest/session/validate	Validates a user session token from an authentication provider
Parameters Name Type Required Description token string Yes Authentication token to validate provider string Yes Name of the authentication provider (e.g., 'oauth', 'local')
Returns Type: object Description: Response indicating whether the session is valid Fields Name Type Description success boolean Indicates if the validation was successful timestamp number Unix timestamp when the response was generated error string Error message (only present when success is false)

WebSocket API

WebSocket connections are established by upgrading a connection at:

/world/ws

Establish Connection

The WebSocket connection is established by creating a connection with search parameters:

TypeScript WS upgrade example

// Format for WebSocket connection URL
const url = new URL(`https://server-domain${Communication.WS_UPGRADE_PATH}`);
url.searchParams.set("token", authToken);    // Authentication token
url.searchParams.set("provider", authProvider);  // Authentication provider name
const ws = new WebSocket(url);

Required URL parameters:

• token: Authentication token obtained from the authentication provider
• provider: Name of the authentication provider (e.g., 'system', 'local')

Message Types

The following message types are available in the WebSocket API:

Message Type	Description
GENERAL_ERROR_RESPONSE	Response sent when a general error occurs during processing
Message Format Type: object Description: Error response with details about the failure Fields Name Type Description timestamp number Unix timestamp when the error occurred requestId string ID of the request that generated the error errorMessage string Detailed error message describing what went wrong type string Message type identifier (GENERAL_ERROR_RESPONSE)
QUERY_REQUEST	Request to execute a query on the server
Parameters Name Type Required Description query string Yes The query string to execute parameters array No Array of parameters to pass to the query requestId string Yes Unique identifier for this request
Message Format Type: object Description: Query request object Fields Name Type Description timestamp number Unix timestamp when the request was created requestId string Unique identifier for this request errorMessage string | null Error message if there was an issue with the request format type string Message type identifier (QUERY_REQUEST) query string The query string to execute parameters array Array of parameters to pass to the query
QUERY_RESPONSE	Response to a query request with results or error information
Message Format Type: object Description: Query response containing results or error details Fields Name Type Description timestamp number Unix timestamp when the response was generated requestId string ID of the request this response is for errorMessage string | null Error message if the query failed, null if successful type string Message type identifier (QUERY_RESPONSE) result T | [] Query results, empty array if no results or error
SYNC_GROUP_UPDATES_RESPONSE	Response containing updates for a sync group
Message Format Type: object Description: Updates for entities in a specific sync group Fields Name Type Description timestamp number Unix timestamp when the updates were generated requestId string ID of the request that triggered these updates errorMessage string | null Error message if there was a problem, null if successful type string Message type identifier (SYNC_GROUP_UPDATES_RESPONSE)
TICK_NOTIFICATION	Notification sent when a server tick occurs
Message Format Type: object Description: Information about the completed tick Fields Name Type Description timestamp number Unix timestamp when the tick notification was sent requestId string ID for this notification errorMessage string | null Error message if there was an issue, null if successful type string Message type identifier (TICK_NOTIFICATION) tick Tick.I_Tick Detailed information about the tick that completed