ADVANCED - Registration and grid APIs

Breakroom offers several APIs designed to help you manage users and regions within your world (here referred to as a grid). Learn how to add users, delete users, update regions, and more.

These APIs require specific access to be granted to your account. If you have purchased your own grid, this will be automatically enabled on the primary user account.

You may send parameters as either POST form_data, or as Query parameters on the URL.

All APIs require you send three additional POST parameters - adminname, adminpwd,and gridid.These should be the username and password of an account on the grid with administrator rights, along with the grid with which you intend to interface. We recommend creating a new user for this role specifically.

User Management APIs

post
Register User

https://sine.space/worldapi/externalapi/add_user
This endpoint allows you to register new users automatically.
Request
Response
Request
Query Parameters
gridid
required
integer
The unique grid ID where the user will be registered.
password
required
string
The user's initial password.
email
required
string
The user's e-mail address. We will not send any messages to this address unless requested by the user (e.g. password reset).
username
required
string
The desired username. If a particular username is already taken, an interation on the provided name will be assigned to the account (e.g. "User Name01").
playeroutfitid
required
integer
The "Outfit ID" the user should be wearing when they first log in. As this creates "free" copies of items that may be listed as paid items on our Marketplace, the creator of the items must be an administrator of the grid in question.
Response
200: OK
User account has been created.
<?xml version="1.0" encoding="utf-8"?>
<AddUserResponse><UserID>2099396</UserID></AddUserResponse>
400: Bad Request
Bad or invalid input, or similar.
<?xml version="1.0" encoding="utf-8"?>
<Response><code>0</code><message>A user account with that name already exists.</message></Response>

post
Delete User

https://sine.space/worldapi/externalapi/delete_user
Deletes or disables a user account.
Request
Response
Request
Path Parameters
userid
required
integer
The user ID associated with the user account.
Response
200: OK
<?xml version="1.0" encoding="utf-8"?>
<Response><code>1</code><message></message></Response>

post
Update User

https://sine.space/worldapi/externalapi/update_user
Changes information about a user account.
Request
Response
Request
Query Parameters
userid
required
integer
The user ID associated with the user account.
email
optional
string
Updates the user's e-mail address.
password
optional
string
Updates the user's password.
Response
200: OK
<?xml version="1.0" encoding="utf-8"?>
<Response><code>1</code><message></message></Response>

post
Get Users

https://sine.space/worldapi/externalapi/get_users
Returns a bulk list of users associated with the grid.
Request
Response
Request
Query Parameters
userids
optional
string
A comma separated list of user IDs you are interested in returning information about.
offset
optional
integer
The query will return a maximum of 100 records. If more are available, use "offset" to return past this point.
Response
200: OK
<?xml version="1.0" encoding="utf-8"?>
<GetUsersResponse><Users><UserID>2099560</UserID><UserName>username</UserName><Email>[email protected]</Email><Gender>M</Gender></Users><Users><UserID>2099559</UserID><UserName>username2</UserName><Email>[email protected]</Email><Gender>F</Gender></Users></GetUsersResponse>

post
Get User By Email

https://sine.space/worldapi/externalapi/get_user_by_email
Retrieves information about an individual user via their email address
Request
Response
Request
Query Parameters
email
required
string
The e-mail address associated with the account.
Response
200: OK
<?xml version="1.0" encoding="utf-8"?>
<GetUserResponse><UserID>2099560</UserID><UserName>username</UserName><Email>[email protected]</Email><Gender>M</Gender></GetUserResponse>

post
Update Login Region

https://sine.space/worldapi/externalapi/update_login_region
Updates the user, and sets their login scene to the specified ID.
Request
Response
Request
Query Parameters
userid
required
integer
The particular user whose login scene you want to update.
regionid
required
integer
The scene you want to set as the user's login scene. Set to zero to return to grid default.
Response
200: OK
<?xml version="1.0" encoding="utf-8"?>
<Response><code>1</code><message></message></Response>Region APIs
Create Region
Creates a new region on the grid
The user ID to be marked as owner of the region
The item ID for the region template to use
Either "0" for no access, "1" for free-for-all access, "2" for friends-only access, and "3" for approved only access.
The name of the region you wish to create
Region was created successfully
<?xml version="1.0" encoding="utf-8"?>
<CreateRegionResponse><RegionID>152860</RegionID></CreateRegionResponse>
An error was found in the inputs
<?xml version="1.0" encoding="utf-8"?>
<Response><code>0</code><message>Room template not available, please try another.</message></Response>
Set Region Role
The ID of the region
The ID of the user in question
Either "Normal", "Admin", or "Blocked".
<?xml version="1.0" encoding="utf-8"?>
<Response><code>1</code><message></message></Response>
<?xml version="1.0" encoding="utf-8"?>
<Response><code>0</code><message>The data provided is incorrect: role = abc</message></Response>
Get Regions
Requests a list of regions on the Grid
Offsets the results if there is too many to return in a single query.
Return regions owned by this account
A CSV separated list of region IDs to return information about.
<?xml version="1.0" encoding="utf-8"?>
<GetRegionsResponse><Regions><RegionID>50000040</RegionID><RegionName>regionname</RegionName><Owner>2099564</Owner><TemplateID>11</TemplateID><AccessLevel>3</AccessLevel></Regions><Regions><RegionID>50000039</RegionID><RegionName>regionname2</RegionName><Owner>2099563</Owner><TemplateID>11</TemplateID><AccessLevel>1</AccessLevel></Regions><GetRegionsResponse>
Update Region
Updates information about a particular region
The region ID to update information about
If present, changes the name of the region
If present, changes the template of the region to the specified template ID
Either "0" - no access, "1" - free access, "2" friends-only access, and "3" approved only access.

Region APIs

post
Create Region

https://sine.space/worldapi/externalapi/create_region
Creates a new region on the grid.
Request
Response
Request
Query Parameters
owner
required
integer
The user ID to be marked as owner of the region.
templateid
required
integer
The item ID for the region template to use.
accesslevel
required
integer
Either "0" for no access, "1" for free-for-all access, "2" for friends-only access, and "3" for approved only access.
regionname
required
string
The name of the region you wish to create.
Response
200: OK
Region was created successfully.
<?xml version="1.0" encoding="utf-8"?>
<CreateRegionResponse><RegionID>152860</RegionID></CreateRegionResponse>
400: Bad Request
An error was found in the inputs.
<?xml version="1.0" encoding="utf-8"?>
<Response><code>0</code><message>Room template not available, please try another.</message></Response>

post
Set Region Role

https://sine.space/worldapi/externalapi/set_region_role
Sets or changes a user's role within a particular region.
Request
Response
Request
Query Parameters
regionid
required
integer
The ID of the region.
userid
required
integer
The ID of the user in question.
role
required
string
Either "Normal," "Admin," or "Blocked."
Response
200: OK
<?xml version="1.0" encoding="utf-8"?>
<Response><code>1</code><message></message></Response>
400: Bad Request
<?xml version="1.0" encoding="utf-8"?>
<Response><code>0</code><message>The data provided is incorrect: role = abc</message></Response>

post
Get Regions

https://sine.space/worldapi/externalapi/get_regions
Requests a list of regions on the grid.
Request
Response
Request
Query Parameters
offset
optional
integer
Offsets the results if there are too many to return in a single query.
owner
optional
integer
Return regions owned by a particular owner's account.
regionids
optional
string
A CSV list of region IDs to return information about.
Response
200: OK
<?xml version="1.0" encoding="utf-8"?>
<GetRegionsResponse><Regions><RegionID>50000040</RegionID><RegionName>regionname</RegionName><Owner>2099564</Owner><TemplateID>11</TemplateID><AccessLevel>3</AccessLevel></Regions><Regions><RegionID>50000039</RegionID><RegionName>regionname2</RegionName><Owner>2099563</Owner><TemplateID>11</TemplateID><AccessLevel>1</AccessLevel></Regions><GetRegionsResponse>

post
Update Region

https://sine.space/worldapi/externalapi/update_region
Updates information about a particular region.
Request
Response
Request
Query Parameters
regionid
required
integer
The region ID to update information about.
regionname
optional
string
If present, changes the name of the region.
templateid
optional
integer
If present, changes the template of the region to the specified template ID.
accesslevel
optional
integer
Either "0" - no access, "1" - free access, "2" - friends-only access, and "3" - approved only access.
Response
200: OK