Introduction
Welcome to the Spot API documentation. The API is currently in beta phase and we are interested in your feedback. Please read this document to get started. Email dev@spotvirtual.com to request access to the API.
Changelog
- 09/20/2022: Added thread and event APIs.
Basics
We currently offer a REST-based API.
Authentication
Before being able to access the API, you first have to create an access token. In your Spot user's preferences, navigate to the Advanced tab and enable the Developer mode toggle. Once the developer mode has been enabled, you will notice that a new API tab have appeared in the left side menu. It is in the API tab that you can create and manage access tokens.
Authorization
You can control what your access token has access to. After creating a new token, you must decide what scopes (types of resources and level of access) and what teams the token is able to access. At this moment you can only access resources that belong to specific orgs (this means that at the moment you can't access things like direct messages using the API).
Currently the API supports:
- worlds and entities (i.e. spaces and the things in them)
- threads and events (i.e. channels and the messages in them)
You can select the level of access:
- read-only
- read-write access (can modify existing data)
- admin access (can create and delete data)
More scopes will be added as we evolve the API.
Rate Limiting
At the moment we do not enforce any rate limits. We do ask that you apply common sense and do not overwhelm our API. We reserve the right to disable access tokens that cause problems.
Errors
The API aims to return proper status codes in all cases, and we recommend that you use them to see whether or not your requests were successful. If you receive errors then we recommend that you throttle and wait a moment before you retry the request. Here's a list of common status codes and what they mean:
200 - OK
204 - No Content
400 - Bad Request
401 - Unauthorized
403 - Forbidden
404 - Not Found
500 - Internal Server Error
502 - Bad Gateway
503 - Service Unavailable
504 - Gateway Timeout
Most successful requests result in the 200 status code. Some endpoints use the 204 status code to indicate a successful request (e.g. when deleting entities).
A response with the 400 status code means that the URL parameters or request data is somehow invalid.
A response with the 401 status code most likely means the access token has been deleted or disabled.
A response with the 403 status code can mean a couple of different things:
- the resource does not exist
- you have not been granted access to the resource
- you no longer have the required membership to the team (some actions require admin membership)
A response with the 404 status code means that the resource or entity does not exist.
5xx errors usually means that Spot is experiencing server issues, a planned downtime, or the input data was unexpected and resulted in a server error.
Making requests
Now that you have created an access token and authorized access for it, you are ready to make your first request.
Worlds and entities
Entity endpoint
First we need to decide what data we want to retrieve and what endpoint to use. The easiest endpoint to use is an endpoint to retrieve an entity and its properties. To get the endpoint for an object inside of Spot, simply right-click on it and click Edit.
You will notice that since Developer Mode is enabled, there's a new text field at the bottom.
This is the endpoint for the entity itself. Click the Copy button to copy it.
Retrieve entity data
Use curl to retrieve the entity data:
curl -H "Authorization: Bearer spot_abcdefgijklmnopqrstuvwxyz01234567890" \https://spotvirtual.com/api/world/cebc47ed-72ab-4522-bbc7-632e5adff627/entity/b81b4dc0-94e6-4771-9ae6-39bcf8941590
The above command should return JSON data similar to the following:
{"type": 2,"entityId": "b81b4dc0-94e6-4771-9ae6-39bcf8941590","assetId": "7c9f9680-878a-402e-a53c-12766d4b8ed2","transform": {"position": [15.5, 0.004999999999999999, 2.25],"rotation": [0, 0, 0, 1],"scale": [1, 1, 1]},"eventType": 6,"userId": "a659f37b-9492-4553-9e5c-10d34351f073","clientRev": 262,"properties": {"Primary Color": "#c3c3c3"}}
Update entity properties
We can send a PUT request to the same endpoint to update the entity. For example, to update the Primary Color property, we can run the following:
Use curl to update the Primary Color property:
curl -H "Authorization: Bearer spot_abcdefgijklmnopqrstuvwxyz01234567890" \-H "Content-Type: application/json" \-X PUT \-d '{"properties":{"Primary Color":"#e53e3e"}}' \https://spotvirtual.com/api/world/cebc47ed-72ab-4522-bbc7-632e5adff627/entity/b81b4dc0-94e6-4771-9ae6-39bcf8941590
The bean bag has now turned red.
Create a new entity
We can create a copy of the bean bag with the following request. I have changed the position slightly, otherwise the copy would end up in the same position as the original.
curl -H "Authorization: Bearer spot_abcdefgijklmnopqrstuvwxyz01234567890" \-H "Content-Type: application/json" \-X POST \-d '{"type":2,"assetId":"7c9f9680-878a-402e-a53c-12766d4b8ed2","transform":{"position":[18.5,0.004999999999999999,2.25],"rotation":[0,0,0,1],"scale":[1,1,1]},"eventType":6,"userId":"a659f37b-9492-4553-9e5c-10d34351f073","properties":{"Primary Color":"#e53e3e"}}' \https://spotvirtual.com/api/world/cebc47ed-72ab-4522-bbc7-632e5adff627/entities
The above command should return JSON data similar to the following:
{"type": 2,"eventType": 6,"entityId": "fc2e3b3f-0b52-4f2f-b6ac-2915750692a2","userId": "a659f37b-9492-4553-9e5c-10d34351f073","assetId": "7c9f9680-878a-402e-a53c-12766d4b8ed2","transform": {"position": [18.5,0.004999999999999999,2.25],"rotation": [0,0,0,1],"scale": [1,1,1]},"properties": {"Primary Color": "#e53e3e"}}
There are now two red bean bag chairs.
The response above includes the state of the new entity, including its entityId which was generated by the server.
Delete an entity
If we don't like the new bean bag then we can delete it with the following request:
curl -H "Authorization: Bearer spot_abcdefgijklmnopqrstuvwxyz01234567890" \-X DELETE \https://spotvirtual.com/api/world/cebc47ed-72ab-4522-bbc7-632e5adff627/entity/fc2e3b3f-0b52-4f2f-b6ac-2915750692a2
The command will not print any output if it is successful. The bean bag that we created before should have disappeared from the world.
Threads and events
Thread and event objects represent the chat and the messages in them. You can access both channels and the room chat through the thread object.
Retrieve thread information
First retrieve the thread ID for the channel you are interested in. Open the channel details and scroll down to find the thread ID.
curl -H "Authorization: Bearer spot_abcdefgijklmnopqrstuvwxyz01234567890" \https://spotvirtual.com/api/thread/eaa217c6-82d0-4dce-b40b-ee76c261bfff
The above command should return JSON data similar to the following:
{"isArchived": false,"id": "eaa217c6-82d0-4dce-b40b-ee76c261bfff","orgId": "c24112b2-f075-4df3-80f0-4cef2ef369a3","type": "Channel","name": "general","description": "All work-based matters.","entityId": null,"spotId": null,"parentEventId": null,"isPrivate": false,"creatorId": "a659f37b-9492-4553-9e5c-10d34351f073","lastMessageId": "4fe84270-8138-4da1-a5dc-4aa531e996cb","lastMessageAt": "2022-09-20T17:44:17.304Z","autoArchiveAfterMilliseconds": null,"updatedAt": "2022-09-20T17:44:17.366Z","createdAt": "2022-09-07T19:17:35.264Z"}
Retrieve messages in a channel
Here I'm retrieving the last two messages in the channel.
curl -H "Authorization: Bearer spot_abcdefgijklmnopqrstuvwxyz01234567890" \https://spotvirtual.com/api/thread/eaa217c6-82d0-4dce-b40b-ee76c261bfff/events?last=2
The above command should return JSON data similar to the following:
{"edges": [{"cursor": "59e5fe4c-d7d2-4b8a-9bde-89317e40f835|1663703880822","node": {"id": "59e5fe4c-d7d2-4b8a-9bde-89317e40f835","type": "ChatMessage","threadId": "eaa217c6-82d0-4dce-b40b-ee76c261bfff","userId": "a659f37b-9492-4553-9e5c-10d34351f073","timestamp": "2022-09-20T19:58:00.822Z","createdAt": "2022-09-20T19:58:00.822Z","orgMembershipId": null,"payload": {"message": "the weather is warm and sunny today","attachedFiles": []}}},{"cursor": "37bfa3b9-6b2c-42d4-9be7-cf8ff522e1f8|1663703881165","node": {"id": "37bfa3b9-6b2c-42d4-9be7-cf8ff522e1f8","type": "ChatMessage","threadId": "eaa217c6-82d0-4dce-b40b-ee76c261bfff","userId": "a659f37b-9492-4553-9e5c-10d34351f073","timestamp": "2022-09-20T19:58:01.165Z","createdAt": "2022-09-20T19:58:01.165Z","orgMembershipId": null,"payload": {"message": "what is everyone doing this week?","attachedFiles": []}}}],"pageInfo": {"startCursor": "59e5fe4c-d7d2-4b8a-9bde-89317e40f835|1663703880822","endCursor": "37bfa3b9-6b2c-42d4-9be7-cf8ff522e1f8|1663703881165","hasPreviousPage": true,"hasNextPage": false}}
To retrieve the next two messages, use the startCursor value in a new before query parameter.
curl -H "Authorization: Bearer spot_abcdefgijklmnopqrstuvwxyz01234567890" \https://spotvirtual.com/api/thread/eaa217c6-82d0-4dce-b40b-ee76c261bfff/events?last=2&before=59e5fe4c-d7d2-4b8a-9bde-89317e40f835|1663703880822
The above command should return JSON data similar to the following:
{"edges": [{"cursor": "4f3b2294-f31c-4733-81ef-9e383ed6be8c|1663703880301","node": {"id": "4f3b2294-f31c-4733-81ef-9e383ed6be8c","type": "ChatMessage","threadId": "eaa217c6-82d0-4dce-b40b-ee76c261bfff","userId": "a659f37b-9492-4553-9e5c-10d34351f073","timestamp": "2022-09-20T19:58:00.301Z","createdAt": "2022-09-20T19:58:00.301Z","orgMembershipId": null,"payload": {"message": "good morning everyone!","attachedFiles": []}}},{"cursor": "480eb4ee-4106-4dad-9e21-b75c3d6521ea|1663703880592","node": {"id": "480eb4ee-4106-4dad-9e21-b75c3d6521ea","type": "ChatMessage","threadId": "eaa217c6-82d0-4dce-b40b-ee76c261bfff","userId": "a659f37b-9492-4553-9e5c-10d34351f073","timestamp": "2022-09-20T19:58:00.592Z","createdAt": "2022-09-20T19:58:00.592Z","orgMembershipId": null,"payload": {"message": "this is a thread","threadInfo": {"threadId": "4fe77aae-bf8e-4906-a76e-25055d56a639","participants": "a659f37b-9492-4553-9e5c-10d34351f073","lastMessageAt": "2022-09-20T20:16:12.223Z","numberOfMessages": 2},"attachedFiles": []}}}],"pageInfo": {"startCursor": "4f3b2294-f31c-4733-81ef-9e383ed6be8c|1663703880301","endCursor": "480eb4ee-4106-4dad-9e21-b75c3d6521ea|1663703880592","hasPreviousPage": true,"hasNextPage": false}}
As you can see one of the messages has a reply thread associated with it, with two messages in it. You can retrieve that thread separately.
curl -H "Authorization: Bearer spot_abcdefgijklmnopqrstuvwxyz01234567890" \https://spotvirtual.com/api/thread/4fe77aae-bf8e-4906-a76e-25055d56a639/events
The above command should return JSON data similar to the following:
{"edges": [{"cursor": "2bf70272-6f73-4865-8a32-04f05f284c75|1663704393004","node": {"id": "2bf70272-6f73-4865-8a32-04f05f284c75","type": "ThreadCreated","threadId": "4fe77aae-bf8e-4906-a76e-25055d56a639","userId": "a659f37b-9492-4553-9e5c-10d34351f073","timestamp": "2022-09-20T20:06:33.004Z","createdAt": "2022-09-20T20:06:33.004Z","orgMembershipId": null}},{"cursor": "01f37544-e93f-432c-b762-7f9a386a2705|1663704955451","node": {"id": "01f37544-e93f-432c-b762-7f9a386a2705","type": "ChatMessage","threadId": "4fe77aae-bf8e-4906-a76e-25055d56a639","userId": "a659f37b-9492-4553-9e5c-10d34351f073","timestamp": "2022-09-20T20:15:55.451Z","createdAt": "2022-09-20T20:15:55.451Z","orgMembershipId": null,"payload": {"message": "this thread is great!","attachedFiles": []}}},{"cursor": "e4bc2da0-46b6-4446-9874-95db9af8aad2|1663704972078","node": {"id": "e4bc2da0-46b6-4446-9874-95db9af8aad2","type": "ChatMessage","threadId": "4fe77aae-bf8e-4906-a76e-25055d56a639","userId": "a659f37b-9492-4553-9e5c-10d34351f073","timestamp": "2022-09-20T20:16:12.078Z","createdAt": "2022-09-20T20:16:12.078Z","orgMembershipId": null,"payload": {"message": ":tada: :sun_with_face: ","attachedFiles": []}}}],"pageInfo": {"startCursor": "2bf70272-6f73-4865-8a32-04f05f284c75|1663704393004","endCursor": "e4bc2da0-46b6-4446-9874-95db9af8aad2|1663704972078","hasPreviousPage": false,"hasNextPage": false}}
Create a new event
Here I'm posting a new message in the first thread.
curl -H "Authorization: Bearer spot_abcdefgijklmnopqrstuvwxyz01234567890" \-H "Content-Type: application/json" \-X POST \-d '{"message":"I am planning a birthday party for tomorrow :cake:"}' \https://spotvirtual.com/api/thread/eaa217c6-82d0-4dce-b40b-ee76c261bfff/events
The above command should return JSON data similar to the following:
{"threadId": "eaa217c6-82d0-4dce-b40b-ee76c261bfff","userId": "a659f37b-9492-4553-9e5c-10d34351f073","payload": {"message": "I am planning a birthday party for tomorrow :cake:","attachedFiles": []},"orgMembershipId": null,"id": "8e4a1d00-7dc9-4ee6-add5-e9e71ab936fd","timestamp": "2022-09-20T20:37:00.382Z","createdAt": "2022-09-20T20:37:00.382Z"}
See the list of endpoints below for more actions.
Endpoints
GET /api/world/<worldId>/floorplan
Get the floorplan of the world. At the moment you can't update the floorplan through the API.
GET /api/world/<worldId>/entities
Get a list of all of the entities in the world (including all of the users).
POST /api/world/<worldId>/entities
Create a new entity. Requires the world admin scope.
GET /api/world/<worldId>/entity/<entityId>
Get a single entity.
PUT /api/world/<worldId>/entity/<entityId>
Update an entity.
DELETE /api/world/<worldId>/entity/<entityId>
Delete an entity. Requires the world admin scope.
Thread
GET /api/thread/<threadId>
Get thread information. Requires the thread read scope.
PUT /api/thread/<threadId>
Update the thread. Requires the thread write scope. You can update the name, description and isPrivate fields.
DELETE /api/thread/<threadId>
Delete the thread. Requires the thread admin scope.
GET /api/thread/<threadId>/events
Get a paginated list of events in the thread. Requires the event read scope.
By default the last 30 events will be retrieved. You can retrieve the initial events using the first and last query parameters. You can then paginate forwards and backwards using the before and after query parameters.
POST /api/thread/<threadId>/events
Create a new event in the thread. Requires the event write scope. You can only specify the message field. The event creator will be the user that created the access token.
Event
GET /api/event/<eventId>
Get information for a single event. Requires the event read scope.
PUT /api/event/<eventId>
Update the event. Requires the event write scope. You can only update the message field.
DELETE /api/event/<eventId>
Delete the event. Requires the event admin scope.
Data objects
World Floorplan
The floorplan has the following shape:
Click to expand example data
{"height": 6,"corners": {"0": {"x": -21,"y": 15},"1": {"x": -21,"y": 37},"2": {"x": 16,"y": 37},"3": {"x": 16,"y": 15},"0b9441c5-a3b1-448d-85be-be774f075ff8": {"x": 7,"y": 37},"5ae3c71b-0b95-4051-85d0-fa86fa06b860": {"x": 7,"y": 50},"6ee6feaa-4a2c-4694-999b-0d8aeae59b6a": {"x": -24,"y": 37},"85b36252-b679-48eb-83a5-e32d59eae9ff": {"x": -24,"y": 50}},"walls": [{"corner1": "0","corner2": "1","frontMaterial": {"materialId": "1b36d86c-a65d-4532-abb2-86e7539ace62","properties": {"Color": "#1FFF4A","diffuseColor": "#9ad5fa"}},"backMaterial": {"materialId": "1b36d86c-a65d-4532-abb2-86e7539ace62","properties": {"Color": "#1FFF4A","diffuseColor": "#9ad5fa"}}},{"corner1": "1","corner2": "0b9441c5-a3b1-448d-85be-be774f075ff8","frontMaterial": {"materialId": "fb40d5e0-1bb8-4cb4-bdeb-ebb874d03ad1","properties": {"Color": "#1FFF4A","diffuseColor": "#fbfbfb"}},"backMaterial": {"materialId": "faa2c208-2455-4f23-986b-28ea94929c26","properties": {"Color": "#9FDEA6","diffuseColor": "#fbfbfb"}}},{"corner1": "2","corner2": "3","frontMaterial": {"materialId": "1b36d86c-a65d-4532-abb2-86e7539ace62","properties": {"Color": "#1FFF4A","diffuseColor": "#9ad5fa"}},"backMaterial": {"materialId": "1b36d86c-a65d-4532-abb2-86e7539ace62","properties": {"Color": "#1FFF4A","diffuseColor": "#9ad5fa"}}},{"corner1": "3","corner2": "0","frontMaterial": {"materialId": "1b36d86c-a65d-4532-abb2-86e7539ace62","properties": {"Color": "#1FFF4A","diffuseColor": "#9ad5fa"}},"backMaterial": {"materialId": "1b36d86c-a65d-4532-abb2-86e7539ace62","properties": {"Color": "#1FFF4A","diffuseColor": "#9ad5fa"}}},{"corner1": "1","corner2": "6ee6feaa-4a2c-4694-999b-0d8aeae59b6a","thickness": 0,"frontMaterial": {"materialId": "1b36d86c-a65d-4532-abb2-86e7539ace62","properties": {"Color": "#1FFF4A","diffuseColor": "#9ad5fa"}}},{"corner1": "6ee6feaa-4a2c-4694-999b-0d8aeae59b6a","corner2": "85b36252-b679-48eb-83a5-e32d59eae9ff","thickness": 0,"frontMaterial": {"materialId": "1b36d86c-a65d-4532-abb2-86e7539ace62","properties": {"Color": "#1FFF4A","diffuseColor": "#9ad5fa"}}},{"corner1": "85b36252-b679-48eb-83a5-e32d59eae9ff","corner2": "5ae3c71b-0b95-4051-85d0-fa86fa06b860","thickness": 0,"frontMaterial": {"materialId": "1b36d86c-a65d-4532-abb2-86e7539ace62","properties": {"Color": "#1FFF4A","diffuseColor": "#9ad5fa"}}},{"corner1": "5ae3c71b-0b95-4051-85d0-fa86fa06b860","corner2": "0b9441c5-a3b1-448d-85be-be774f075ff8","thickness": 0,"frontMaterial": {"materialId": "1b36d86c-a65d-4532-abb2-86e7539ace62","properties": {"Color": "#1FFF4A","diffuseColor": "#9ad5fa"}}},{"corner1": "0b9441c5-a3b1-448d-85be-be774f075ff8","corner2": "2","frontMaterial": {"materialId": "fb40d5e0-1bb8-4cb4-bdeb-ebb874d03ad1","properties": {"Color": "#1FFF4A","diffuseColor": "#fbfbfb"}},"backMaterial": {"materialId": "faa2c208-2455-4f23-986b-28ea94929c26","properties": {"diffuseColor": "#fbfbfb"}}}],"rooms": [{"cornerIds": ["0b9441c5-a3b1-448d-85be-be774f075ff8","5ae3c71b-0b95-4051-85d0-fa86fa06b860","85b36252-b679-48eb-83a5-e32d59eae9ff","6ee6feaa-4a2c-4694-999b-0d8aeae59b6a","1"],"id": "e19841af-d56b-4bb0-a057-9631d160acae","floorMaterial": {"materialId": "8d356e1d-f81c-4ead-95cc-2d5f35b16220","properties": {"alpha": "","scaleFactor": "4","diffuseColor": "#fbfbfb"}},"isOutside": true},{"cornerIds": ["0","3","2","0b9441c5-a3b1-448d-85be-be774f075ff8","1"],"id": "7bf0bdf2-b29d-43db-80b6-567d15434ff2","floorMaterial": {"materialId": "4b3971ff-b9cb-4c2a-a854-d3f29006ff8e","properties": {"diffuseColor": ""}}}],"floorMaterial": {"materialId": "1e95cc53-1224-4b13-93c3-2f480b11c4ea","properties": {"Color": "#C3C3C3","diffuseColor": "#FECC96"}},"wallMaterial": {"materialId": "0bcc2b69-3a8d-5ff8-bd13-9b8dc874ad9b","properties": {"Color": "#cdd2cc"}},"exteriorMaterial": {"materialId": "0bcc2b69-3a8d-5ff8-bd13-9b8dc874ad9b","properties": {"Color": "#888888"}},"wallThickness": 0.32,"topColor": "#CCEAFC","lightDirection": [0,-1,0],"lightColor": "#FFFFFF","ambientColor": "#999999"}
World Entity
A world entity has the following shape:
Click to expand example data
{"type": 2,"entityId": "b81b4dc0-94e6-4771-9ae6-39bcf8941590","assetId": "7c9f9680-878a-402e-a53c-12766d4b8ed2","transform": {"position": [15.5, 0.004999999999999999, 2.25],"rotation": [0, 0, 0, 1],"scale": [1, 1, 1]},"eventType": 6,"userId": "a659f37b-9492-4553-9e5c-10d34351f073","clientRev": 262, // increments every time a user modifies the entity"properties": {// varies depending on the asset}}
Thread Entity
A thread has the following shape:
Click to expand example data
{"isArchived": false,"id": "eaa217c6-82d0-4dce-b40b-ee76c261bfff","orgId": "c24112b2-f075-4df3-80f0-4cef2ef369a3","type": "Channel","name": "general","description": "All work-based matters.","entityId": null,"spotId": null,"parentEventId": null,"isPrivate": false,"creatorId": "a659f37b-9492-4553-9e5c-10d34351f073","lastMessageId": "4fe84270-8138-4da1-a5dc-4aa531e996cb","lastMessageAt": "2022-09-20T17:44:17.304Z","autoArchiveAfterMilliseconds": null,"updatedAt": "2022-09-20T17:44:17.366Z","createdAt": "2022-09-07T19:17:35.264Z"}
Event Entity
An event has the following shape:
Click to expand example data
{"id": "4fe84270-8138-4da1-a5dc-4aa531e996cb","type": "ChatMessage","threadId": "eaa217c6-82d0-4dce-b40b-ee76c261bfff","userId": "a659f37b-9492-4553-9e5c-10d34351f073","timestamp": "2022-09-20T17:44:17.304Z","createdAt": "2022-09-20T17:44:17.304Z","orgMembershipId": null,"payload": {"message": "Hello world","attachedFiles": []}}