Map Building Admin User Developer Tutorials Login Get Started Search ctrl K

Api Reference

Camera Room API

Protocol

Chat Why gRPC?

Controls Room API Client libraries

Protobuf file
Event
The Room API is a gRPC-based API that allows an external server to connect to a room and to perform actions such as
Map Editor API reading/modifying/listening to a room variable.
Metadata
The Room API is a server to server API. If you are looking for a "client to server" API (for instance to add a dynamic behavior to a map),
Navigation look at the scripting API.
Player
The Room API is not designed to create rooms or to manage members or authorizations on who can enter a room. If you are looking
Players
for an API to do this, look for the AdminAPI (in self-hosted mode) or the inbound or hooks if you are using the WorkAdventure SAAS
Room version.

Sound
In WorkAdventure, the state of a room is stored in variables. You can bind those variables to some objects state (for instance to the
Start fact that a door is closed or opened). Or you can use the scripting API to react to variables change.

State
The Room API lets you monitor those room variables, but also allows you to edit them. Through variables, you can therefore establish a
UI 2-ways data channel between your server and what happens in a WorkAdventure room.

Deprecated Functions

Extended utility functions

Tiled Layers

Tiled Properties

Svelte
Protocol
Variables
You connect to the Room API using gRPC over HTTP2.
Scripting Internals

Using Typescript

Map Storage API Why gRPC?

Room API
The Room API must be able to read and edit variables, but must also be able to listen in real-time to variables changes. The real-time
Webhooks aspect of the Room API makes a classic REST API not very well suited. We could have designed the API on Websockets or using
Server-Sent Events, but those are hard to standardize.

The gRPC protocol provides an API that is self-documented (using .proto files), strictly typed, real-time and extremely performant.

SaaS Self Hosted

SELF HOSTED FREE PLAN PREMIUM PLAN

Authentication
In order to connect to the Room API, you will need an authentication token.

You can issue a new authentication token in the administration dashboard of WorkAdventure.

Go to Settings > Developers

In the "Tokens" sections, click on "Create new token".

Give your token a name

Save the token for the next step.

Authentication to the API is done by passing a **X-API-Key** header in the gRPC metadata on each call to the API.

Endpoint
The Room API is available on the following endpoint:

Hostname Port

room-api.workadventu.re 443

Client libraries
SELF HOSTED FREE PLAN PREMIUM PLAN

TypeScript / JavaScript : @workadventure/room-api-client

You want to contribute or create a new client ? Please check the existing clients before.

Protobuf file
SELF HOSTED FREE PLAN PREMIUM PLAN

The Protobuf file is available here.

INFO

Need help 🆘

Contact us or write us to [email protected]

Edit this page

Previous Next
« Map Storage API Webhooks »

Docs Need help ? Follow us

Map Building Book a demo Linkedin

Admin Discord Twitter

Developer GitHub Facebook

Copyright © 2024 workadventu.re - All Rights Reserved