Connect AI assistants to Orbix360

whoami · Who am I

Returns the Orbix360 account this connection acts for: user id, display name, email, plan, and the permissions the token carries. Call it to check the connection works.

No inputs.

Example: whoami {}

get_account · Account and plan limits

Returns the plan this account is on, whether it may make tours private and use its own branding (no watermark, embedding), how many multi-image and single-image tours it has and may still create (including any bonus, from Premium Tours, shared tours or answering the use-case question, and its cap), the photo-count and file-size caps for one tour (null = no cap), and the Pricing and Billing page addresses. Call it before creating a tour or adding photos.

No inputs.

Example: get_account {}

list_tours · List my tours

Lists this account's tours, newest created first, a page at a time. Each tour has its id, name, kind (single- or multi-image), scene count, visibility, last-changed time and a thumbnail. Pass nameContains to search by name (case-insensitive) and the previous answer's nextCursor as cursor for the next page; nextCursor is null on the last page. A filtered search reads a bounded number of tours per call: when scanLimited is true, continue with nextCursor.

limit · integer · optional

Tours per page, 1–50 (default 20). (at least 1, at most 50)

cursor · string · optional

nextCursor from the previous answer of the same search. (at least 1 character, up to 2048 characters)

nameContains · string · optional

Only tours whose name contains this text (case-insensitive). (up to 200 characters)

Example: list_tours { "nameContains": "lake house" }

get_tour · Read a tour

Returns one of your tours as the viewer shows it: name, visibility, autorotate, the premium state, stateRevision (quote it when you edit the tour), the scenes in order (title, whether the title is only a "Photo N" placeholder, photo type, thumbnail, processing status ready / processing / missing / unknown, heading = the yaw the scene opens on, and generated = sent as AI-generated), every navigation hotspot, info hotspot and flat image, and every Element (Script Elements with template, parameters and distance; older ones as read-only summaries), each with its position as yaw / pitch in degrees on the scene's panorama: yaw 0 = the photo's centre column, positive to the right, in (-180, 180]; pitch 0 = the horizon, +90 = straight up.

tourId · string · required

The tour id, as list_tours returns it. (up to 32 characters, a fixed format)

Example: get_tour { "tourId": "…" }

create_tour · Create tour

Creates a new 360° virtual tour in the account. kind "multi" holds several photos linked by navigation hotspots; "single" holds one photo. Visibility defaults to public; private needs a Pro plan. Free accounts can create a limited number of tours. Returns the tour id, links to view and edit it, and what to do next.

Counts toward the plan's tour allowance.

name · string · required

The tour name, up to 200 characters. (at least 1 character, up to 200 characters)

kind · one of: multi, single · required

"multi" for a multi-image tour, "single" for a single-image tour.

visibility · one of: public, private · optional

Defaults to "public". "private" needs a Pro plan.

Example: create_tour { "name": "Lake House", "kind": "multi" }

update_tour · Update tour

Changes a tour's name, visibility and/or auto-rotation. Give at least one of them. All the given settings change together, or none do when one is refused. Making a tour private needs a Pro plan or a Premium Tour on that tour. Settings the tour already has are left as they are, so repeating a call changes nothing.

Private tours need a Pro account or a Premium Tour.

tourId · string · required

The tour id. (a fixed format)

name · string · optional

A new name, up to 200 characters. (at least 1 character, up to 200 characters)

visibility · one of: public, private · optional

"private" needs a Pro plan or a Premium Tour on this tour.

autorotate · boolean · optional

Whether the tour turns slowly on its own when opened.

Example: update_tour { "tourId": "…", "visibility": "private" }

delete_tour · Delete tour

Permanently deletes a tour and its photos. This cannot be undone. confirmName must be the tour's exact current name, as the owner confirmed it. A Premium Tour subscription on the tour stops renewing; the answer says so.

Cannot be undone. Needs the tour's exact current name as confirmName, so confirm with the owner first.

tourId · string · required

The tour id. (a fixed format)

confirmName · string · required

The tour's exact current name, confirmed with the owner.

Example: delete_tour { "tourId": "…", "confirmName": "Lake House" }

get_share_links · Share links for a tour

Returns the addresses to share one of your tours: the public page, the short link (null when the tour has none), the share link the Orbix360 share box copies, the viewer link, your editor link and, when this tour may be embedded (Pro plan or a Premium Tour for the tour), an embed snippet; otherwise embedUnavailable says what unlocks it. These links are not tracked, so sharing them does not earn shared-tour credit.

The embed snippet is offered only to a Pro account or a Premium Tour.

tourId · string · required

The tour id, as list_tours returns it. (up to 32 characters, a fixed format)

Example: get_share_links { "tourId": "…" }

add_photo_from_url · Add a photo from a URL

Add a 360° photo to one of the user's tours from a public https URL. The server downloads the image (JPEG, PNG or WebP), checks it, and adds it as the last scene of the tour. 360_mono photos must be equirectangular: twice as wide as tall (2:1). Use 360_pano for a wider panorama. For an image made by an AI image generator (yours or the user's), set generated: true: a 360_mono image from 1.74:1 to 2.40:1 (16:9 to 2.4:1) is then stretched to 2:1 and its left and right edges blended so no seam shows. Returns status "processing": call get_photo_status with the photo id until it is "ready" before placing hotspots on it. For a file on this computer, use create_photo_upload instead.

With generated: true, an AI-generated image from 1.74:1 to 2.40:1 is stretched to 2:1 and its seam blended.

tourId · string · required

The tour id, as list_tours returns it. (up to 32 characters, a fixed format)

url · string · required

A public https URL of the image itself (not a web page showing it). (up to 2048 characters)

title · string · optional

The scene title, e.g. "Kitchen". (at least 1 character, up to 200 characters)

photoType · one of: 360_mono, 360_pano · required

360_mono for an equirectangular 2:1 photo; 360_pano for a wider panorama.

generated · boolean · optional

Set true for an image made by an AI image generator. A 360_mono image from 1.74:1 to 2.40:1 is then stretched to 2:1 and its seam blended; without it, a 360_mono image must already be 2:1.

Example: add_photo_from_url { "tourId": "…", "url": "https://example.com/living-room.jpg", "photoType": "360_mono" }

create_photo_upload · Upload a photo from this computer or the browser

Prepare an upload of a photo file into one of the user's tours. It works in every client, including web and chat apps that cannot run commands. In a chat or web app, and whenever the user attached the photos to the conversation: you cannot send the file yourself and do not need to. Call this tool once per photo, give the user each uploadPage.url, and ask them to open it in a browser signed in to Orbix360 and drop that photo there (each link takes one file, once, within 2 hours). Do not ask the user to run commands. Agents that can run shell commands on the computer holding the file: run the returned command exactly as given, from the folder the filename is relative to. Either way, then call get_photo_status with the photo id until it is "ready". The file must be a JPEG; a 360_mono photo must be equirectangular (2:1). Size, format and shape are checked after the upload: a file that fails is removed and get_photo_status says why. The upload address and the page link work for this one photo only. If they expire before the file is sent, call create_photo_upload again with the same photoId for new ones (nothing new is added to the tour). For an image on the web, use add_photo_from_url instead. For an image made by an AI image generator, set generated: true: the file may then also be a PNG or WebP, and a 360_mono image from 1.74:1 to 2.40:1 (16:9 to 2.4:1) is stretched to 2:1 with its left and right edges blended.

Works in every client: answers an uploadPage link (signed-in owner, 2 hours, one file) that chat and web apps hand to the user, and an upload command for agents that can run shell commands.

With generated: true the file may also be a PNG or WebP; pass photoId to get a new command and link for a photo still waiting for its file.

tourId · string · required

The tour id, as list_tours returns it. (up to 32 characters, a fixed format)

filename · string · required

The .jpg / .jpeg file (or .png / .webp with generated: true). In a chat or web app, its name as the user attached it or will drop it, e.g. R0010027.jpg. For an agent with a shell, its local path, as the upload command should name it. (at least 1 character, up to 255 characters)

photoType · one of: 360_mono, 360_pano · optional

360_mono for an equirectangular 2:1 photo; 360_pano for a wider panorama. Required unless photoId is given.

title · string · optional

The scene title, e.g. "Living room". (at least 1 character, up to 200 characters)

generated · boolean · optional

Set true for an image made by an AI image generator: PNG / WebP are accepted, and a 360_mono image from 1.74:1 to 2.40:1 is stretched to 2:1 and its seam blended.

photoId · string · optional

To get a new command and page link for a photo that is still waiting for its file (e.g. after the link expired). Returns the same photo id; nothing new is added to the tour. (a fixed format)

Example: create_photo_upload { "tourId": "…", "filename": "kitchen.jpg", "photoType": "360_mono" }

get_photo_status · Check photo status

Check whether photos added with add_photo_from_url or create_photo_upload are ready. Each photo is pending_upload (run its upload command), processing (call again in a few seconds), ready, failed (with a reason; the photo has been removed from the tour), or not_found. generated says whether the photo was sent as AI-generated. One call waits up to about 10 seconds for photos that are still processing. Keep calling until every photo is ready or failed (allSettled is true).

tourId · string · required

The tour id, as list_tours returns it. (up to 32 characters, a fixed format)

photoIds · list of string · required

Up to 20 photo ids returned by add_photo_from_url or create_photo_upload. (at least 1 item, up to 20 items)

Example: get_photo_status { "tourId": "…", "photoIds": ["…"] }

update_scene · Rename a scene

Sets the title of one photo (scene) in a tour, as Organize Photos does in the Orbix360 web editor. Get the tour id and scene ids from get_tour. The title is trimmed and may be up to 200 characters. Returns the tour's scenes in order afterwards.

tourId · string · required

The tour id, as list_tours and get_tour list it. (at least 1 character)

sceneId · string or integer · required

The scene (photo) id, as get_tour lists it.

title · string · required

The new scene title.

Example: update_scene { "tourId": "…", "sceneId": "…", "title": "Kitchen" }

reorder_scenes · Reorder scenes

Sets the order of a multi-image tour's photos (scenes), as Organize Photos does in the Orbix360 web editor. `order` must list every scene id from get_tour exactly once, first scene first. A photo still shown under a position placeholder such as "Photo 3" keeps that title. Returns the scenes in the new order.

Every scene id exactly once.

tourId · string · required

The tour id, as list_tours and get_tour list it. (at least 1 character)

order · list of string or integer · required

Every scene id of the tour exactly once, in the new order. (at least 1 item, up to 500 items)

Example: reorder_scenes { "tourId": "…", "order": ["…", "…", "…"] }

set_scene_heading · Set the direction a scene opens on

Sets the direction a visitor first faces when a scene opens, as Change Orientation does in the Orbix360 web editor, and regenerates the scene's thumbnail from the photo looking that way. yaw is in degrees on the scene's photo (0 = the photo's centre column, positive to the right; any value is wrapped into (-180, 180]), the same coordinates render_view draws: find the place with render_view and pass its yaw. pitch (default 0) only tilts the thumbnail; every scene opens level with the horizon. The tour's first scene's thumbnail is the tour's card image and share image. The photo must be ready (see get_photo_status). Look at the result with render_view centred on the heading if needed.

Also regenerates the scene's thumbnail; the first scene's is the tour's card.

tourId · string · required

The tour id, as list_tours returns it. (up to 32 characters, a fixed format)

sceneId · string or integer · required

The scene (photo) id, as get_tour lists it.

yaw · number · required

The direction to open on, degrees; 0 = the photo's centre column, positive to the right. Wrapped into (-180, 180].

pitch · number · optional

Tilts the thumbnail only, degrees; 0 = horizon, +90 = straight up. Not stored. Default 0. (at least -90, at most 90)

Example: set_scene_heading { "tourId": "…", "sceneId": "…", "yaw": 40 }

delete_scene · Delete a scene

Permanently deletes one photo (scene) from a multi-image tour, with its image files and every navigation hotspot that leads to it. This cannot be undone. A tour always keeps at least one photo. Get the tour id and scene ids from get_tour. Returns the remaining scenes in order.

Cannot be undone; a tour always keeps one photo.

tourId · string · required

The tour id, as list_tours and get_tour list it. (at least 1 character)

sceneId · string or integer · required

The scene (photo) id, as get_tour lists it.

Example: delete_scene { "tourId": "…", "sceneId": "…" }

render_panorama · See a whole scene

Renders one of your scenes' whole 360° photo, flattened into a 2048 × 1024 picture (equirectangular: x is yaw from -180 at the left through 0 at the centre to 180 at the right, where yaw 0 = the photo's centre column, not the scene's opening direction; y is pitch from +90 at the top to -90 at the bottom), with a yaw scale every 30° along the top, pitch marks on the left, and the existing navigation hotspots (N1…), info hotspots (I1…) and flat-image outlines (F1…) labelled and listed with their full ids and coordinates. Script Elements are not drawn here (they are listed; use render_view to see them). A cheap first look to see the room layout; then use render_view to look closer before placing anything, since the panorama is distorted near the top and bottom. Clients that limit picture size may shrink it. Works on your private tours; the photo must be ready (see get_photo_status).

tourId · string · required

The tour id, as list_tours returns it. (up to 32 characters, a fixed format)

sceneId · string or integer · required

The scene (photo) id, as get_tour lists it.

Example: render_panorama { "tourId": "…", "sceneId": "…" }

render_view · Look at a scene

Renders what a visitor sees in one of your scenes looking in a direction, as a JPEG picture you can look at, so you can find things (a door, a fireplace) and read their position before placing a hotspot. The picture is an undistorted 4:3 view centred on yaw / pitch (degrees on the scene's panorama: yaw 0 = the photo's centre column, not the scene's opening direction, positive to the right; pitch 0 = the horizon, +90 = straight up), fov degrees wide (horizontal, 30-120, default 90). Gridlines every 30° are labelled with their yaw (meridians) and pitch (parallels) values, so a point between two lines can be interpolated; existing navigation hotspots (N1…), info hotspots (I1…) and flat-image outlines (F1…) are drawn and listed with their full ids and coordinates in the answer. The scene's Script Elements are drawn as visitors see them, 1 second after they start (the same call gives the same picture), and the answer's elements list says which were drawn, not in view or not drawn and why; older A-Frame Elements and video templates are listed but not drawn. To check a position, render again centred on it: the point is then at the centre of the picture. Use render_panorama first for a cheap look at the whole scene. Works on your private tours; the photo must be ready (see get_photo_status).

Renders have their own per-minute and per-hour limit.

tourId · string · required

The tour id, as list_tours returns it. (up to 32 characters, a fixed format)

sceneId · string or integer · required

The scene (photo) id, as get_tour lists it.

yaw · number · optional

Direction to look, degrees; 0 = the photo's centre column, positive to the right. Any value is wrapped into (-180, 180]. Default 0.

pitch · number · optional

Up / down, degrees; 0 = horizon, +90 = straight up. Default 0. (at least -90, at most 90)

fov · number · optional

Horizontal field of view in degrees (30-120); smaller zooms in. Default 90. (at least 30, at most 120)

width · integer · optional

Picture width in pixels (256-1568); the height is three quarters of it. Default 1024. (at least 256, at most 1568)

showHotspots · boolean · optional

Draw existing hotspots and flat-image outlines with their labels. Default true.

grid · boolean · optional

Draw the 30° yaw / pitch gridlines. Default true.

Example: render_view { "tourId": "…", "sceneId": "…", "yaw": 40, "pitch": -5, "fov": 60 }

add_nav_hotspot · Link two scenes

Adds a navigation hotspot in one scene of a multi-image tour that takes visitors to another scene, as the web editor's Navigation Hotspots panel does. Get scene ids from get_tour and read the place (a doorway, a path) off render_view first. A pair of scenes has at most one link each way: calling again for the same pair moves the existing link. Give returnYaw and returnPitch to also place the link back from toSceneId to fromSceneId in the same call. Returns the hotspot(s) and a link that opens the tour on the scene.

tourId · string · required

The tour id, as list_tours and get_tour list it. (at least 1 character)

fromSceneId · string or integer · required

The scene the hotspot is placed in.

toSceneId · string or integer · required

The scene the hotspot leads to (another scene of the same tour).

yaw · number · required

Where the hotspot sits in fromSceneId: degrees on the scene's photo: 0 = the photo's centre column, positive to the right; any value is wrapped into (-180, 180].

pitch · number · required

Where the hotspot sits in fromSceneId: degrees: 0 = the horizon, +90 = straight up, -90 = straight down. (at least -90, at most 90)

returnYaw · number · optional

Optional: where the way back sits in toSceneId (give with returnPitch): degrees on the scene's photo: 0 = the photo's centre column, positive to the right; any value is wrapped into (-180, 180].

returnPitch · number · optional

Optional: where the way back sits in toSceneId (give with returnYaw): degrees: 0 = the horizon, +90 = straight up, -90 = straight down. (at least -90, at most 90)

Example: add_nav_hotspot { "tourId": "…", "fromSceneId": "…", "toSceneId": "…", "yaw": 40, "pitch": -5, "returnYaw": -150, "returnPitch": -3 }

add_info_hotspot · Add an info hotspot

Adds an info hotspot to a scene: an icon visitors open to read a title and a description, as the web editor's Info Hotspots panel does. Get scene ids from get_tour and read the place off render_view first. Title: up to 50 characters; description: up to 2,000 characters, newlines kept. Text is plain: any HTML markup is removed. Optional look: labelDisplay ("always" shows the text without a hover), labelSide, an icon colour, size and opacity, a built-in icon, and orientation ("floor" / "wall" with rotation) — iconStyle "dark" still works. Text styling (bold, sizes, colours) is set in the web editor only. Works on single-image tours too. Returns the stored hotspot.

labelDisplay "always" shows the text without a hover; orientation "floor" or "wall" lays the icon on a surface, turned by rotation. Text styling (bold, sizes, colours) is set in the web editor.

tourId · string · required

The tour id, as list_tours and get_tour list it. (at least 1 character)

sceneId · string or integer · required

A scene (photo) id, as get_tour lists it.

yaw · number · required

Where the hotspot sits: degrees on the scene's photo: 0 = the photo's centre column, positive to the right; any value is wrapped into (-180, 180].

pitch · number · required

Where the hotspot sits: degrees: 0 = the horizon, +90 = straight up, -90 = straight down. (at least -90, at most 90)

title · string · required

Up to 50 characters of plain text. (up to 1000 characters)

description · string · optional

Up to 2,000 characters of plain text; newlines are kept. (up to 20000 characters)

iconStyle · one of: light, dark · optional

"light" (default) or "dark"; color replaces it.

labelDisplay · one of: hover, always · optional

"hover" (default): visitors see the text when they hover or tap the icon; "always": the text is always shown next to it.

labelSide · one of: above, below, left, right · optional

Where the text sits next to the icon: "above", "below" (default), "left" or "right".

color · string · optional

The icon's colour as #rrggbb (default white). Replaces iconStyle. (a fixed format)

size · integer · optional

The icon's size in percent of the default, 25 to 400 (default 100). (at least 25, at most 400)

opacity · integer · optional

The icon's opacity in percent, 20 to 100 (default 100). (at least 20, at most 100)

orientation · one of: facing, floor, wall · optional

"facing" (default): the icon always faces the visitor; "floor": it lies flat on the floor (or ceiling); "wall": it stands upright facing the scene centre.

rotation · number · optional

Degrees, clockwise as the visitor sees it, for a floor or wall icon; wrapped into (-180, 180].

icon · one of: info, question, pin, star, camera, door, warning, play · optional

A built-in icon: info (default), question, pin, star, camera, door, warning or play.

Example: add_info_hotspot { "tourId": "…", "sceneId": "…", "yaw": 10, "pitch": -20, "title": "Wood stove", "labelDisplay": "always", "color": "#f57c00", "orientation": "floor" }

update_info_hotspot · Change an info hotspot

Changes an existing info hotspot: any of title (up to 50 characters), description (up to 2,000), its look (labelDisplay, labelSide, color, size, opacity, icon, orientation, rotation, iconStyle), and its place (yaw with pitch). Only the fields you give change. A new title or description replaces text styled in the web editor with plain text. Get hotspot ids from get_tour (infoHotspots). An info hotspot stays in its scene: to put it in another scene, remove it and add a new one. Returns the hotspot as stored.

A new title or description replaces text the owner styled in the web editor with plain text; change only the look (size, color, opacity, icon, orientation) to keep it.

tourId · string · required

The tour id, as list_tours and get_tour list it. (at least 1 character)

hotspotId · string · required

The info hotspot id, as get_tour lists it. (at least 1 character, up to 200 characters)

sceneId · string or integer · optional

Optional: the hotspot's own scene (refused if it is another scene).

title · string · optional

Up to 50 characters of plain text. (up to 1000 characters)

description · string · optional

Up to 2,000 characters of plain text. (up to 20000 characters)

iconStyle · one of: light, dark · optional

"light" or "dark"; color replaces it.

labelDisplay · one of: hover, always · optional

"hover" (default): visitors see the text when they hover or tap the icon; "always": the text is always shown next to it.

labelSide · one of: above, below, left, right · optional

Where the text sits next to the icon: "above", "below" (default), "left" or "right".

color · string · optional

The icon's colour as #rrggbb (default white). Replaces iconStyle. (a fixed format)

size · integer · optional

The icon's size in percent of the default, 25 to 400 (default 100). (at least 25, at most 400)

opacity · integer · optional

The icon's opacity in percent, 20 to 100 (default 100). (at least 20, at most 100)

orientation · one of: facing, floor, wall · optional

"facing" (default): the icon always faces the visitor; "floor": it lies flat on the floor (or ceiling); "wall": it stands upright facing the scene centre.

rotation · number · optional

Degrees, clockwise as the visitor sees it, for a floor or wall icon; wrapped into (-180, 180].

icon · one of: info, question, pin, star, camera, door, warning, play · optional

A built-in icon: info (default), question, pin, star, camera, door, warning or play.

yaw · number · optional

The new place (give with pitch): degrees on the scene's photo: 0 = the photo's centre column, positive to the right; any value is wrapped into (-180, 180].

pitch · number · optional

The new place (give with yaw): degrees: 0 = the horizon, +90 = straight up, -90 = straight down. (at least -90, at most 90)

Example: update_info_hotspot { "tourId": "…", "hotspotId": "…", "description": "Installed 2024." }

remove_hotspot · Remove a hotspot

Removes one navigation or info hotspot from a tour. Get hotspot ids from get_tour (navHotspots, infoHotspots). Removing a navigation link leaves the link back from the other scene in place; remove it too if you want both gone. Flat images are removed with remove_flat_image.

tourId · string · required

The tour id, as list_tours and get_tour list it. (at least 1 character)

hotspotId · string · required

The navigation or info hotspot id, as get_tour lists it. (at least 1 character, up to 200 characters)

Example: remove_hotspot { "tourId": "…", "hotspotId": "…" }

add_flat_image · Place a flat image

Places a flat picture (a logo, a sign, a floor plan) in a scene, as the web editor's Flat Images panel does. url must be a public https address of a JPEG, PNG or WebP image of at most 20 MB; it is stored with the tour (shrunk to at most 4096 px; PNG and WebP keep their transparency). Get scene ids from get_tour and choose the place with render_view; render_view then shows the picture's outline. scale 0.5 – 2 (default 1) sets its size, rotation (degrees) turns it in its own plane. Returns the stored flat image.

tourId · string · required

The tour id, as list_tours and get_tour list it. (at least 1 character)

sceneId · string or integer · required

A scene (photo) id, as get_tour lists it.

url · string · required

A public https address of a JPEG, PNG or WebP image (at most 20 MB). (at least 1 character, up to 2048 characters)

yaw · number · required

Where the picture's centre sits: degrees on the scene's photo: 0 = the photo's centre column, positive to the right; any value is wrapped into (-180, 180].

pitch · number · required

Where the picture's centre sits: degrees: 0 = the horizon, +90 = straight up, -90 = straight down. (at least -90, at most 90)

scale · number · optional

Size: 0.5 – 2, default 1. (at least 0.5, at most 2)

rotation · number · optional

Turn in the picture's own plane, degrees (stored in [0, 360)); default 0.

Example: add_flat_image { "tourId": "…", "sceneId": "…", "url": "https://example.com/floor-plan.png", "yaw": 0, "pitch": 0 }

update_flat_image · Change a flat image

Changes an existing flat image: scale (0.5 – 2), rotation (degrees, absolute) and its place (yaw with pitch). Only the fields you give change. Get flat image ids from get_tour (flatImages). To use another picture, remove this one and add a new one.

tourId · string · required

The tour id, as list_tours and get_tour list it. (at least 1 character)

flatImageId · string · required

The flat image id, as get_tour lists it. (at least 1 character, up to 200 characters)

scale · number · optional

Size: 0.5 – 2. (at least 0.5, at most 2)

rotation · number · optional

Turn in the picture's own plane, degrees (absolute, stored in [0, 360)).

yaw · number · optional

The new place (give with pitch): degrees on the scene's photo: 0 = the photo's centre column, positive to the right; any value is wrapped into (-180, 180].

pitch · number · optional

The new place (give with yaw): degrees: 0 = the horizon, +90 = straight up, -90 = straight down. (at least -90, at most 90)

Example: update_flat_image { "tourId": "…", "flatImageId": "…", "scale": 1.5 }

remove_flat_image · Remove a flat image

Removes one flat image from its scene. Get flat image ids from get_tour (flatImages).

tourId · string · required

The tour id, as list_tours and get_tour list it. (at least 1 character)

flatImageId · string · required

The flat image id, as get_tour lists it. (at least 1 character, up to 200 characters)

Example: remove_flat_image { "tourId": "…", "flatImageId": "…" }

get_element_guide · Read the Element guide

The guide to Orbix360 Script Element templates: what a template is, the workflow (search, reuse or fork, write, validate, publish, place), the ctx API declaration, the manifest schema, coordinates and placement, budgets, capabilities, parameter and file types, instances, the scripted input of validate, and worked examples with their source (two of them small games). Call it with no section for the overview and the table of contents, then read the sections you need; example sections are "example:<template id>".

Read the overview first; example sections are "example:<template id>". The same text is offered as orbix360://element-guide/… resources.

section · string · optional

A section id from the table of contents (overview, ctx, manifest, frame, budgets, capabilities, params, instances, input_sequence, examples) or "example:<template id>"; omit for the overview. (at least 1 character, up to 64 characters)

Example: get_element_guide { "section": "overview" }

list_element_templates · List Element templates

Lists Script Element templates: Orbix360's collection (reviewed, shipped with the viewer) and your own My Elements, with name, family, latest version, placement (relative, absolute or scene-wide), capabilities and whether it can be placed on this project. Search here before writing a new template: reuse or fork one that fits. Read one with get_element_template. Your older-format Elements are listed under olderTemplates; convert them with convert_element_template.

Search before writing a template: reuse or fork an Orbix360 template when one fits.

collection · one of: all, orbix, user · optional

"all" (default), "orbix" or "user" (your own).

family · one of: video, image, text, navigation, sound, model, light, environment, effects, games, nft, other · optional

An Element family: video, image, text, navigation, sound, model, light, environment, effects, games, nft, other.

search · string · optional

Words to find in the name, id or description. (up to 100 characters)

Example: list_element_templates { "search": "fireflies" }

get_element_template · Read an Element template

Returns one Element template: the manifest of a version (parameters with types, defaults, ranges and choices; placement; capabilities), the version list and the module source (not for Orbix360 templates that use the viewer's own services). For your own templates it also returns the current draft and its last check. Use the parameters it lists with place_element.

collection · one of: orbix, user · required

"orbix" = Orbix360's collection; "user" = your own My Elements.

template · string · required

A template id (lowercase letters, digits and hyphens), as list_element_templates lists it. (at least 2 characters, up to 48 characters, a fixed format)

version · integer · optional

A published version number; omit for the latest. (at least 1)

Example: get_element_template { "collection": "orbix", "template": "fireflies" }

create_element_template · Create an Element template

Creates a Script Element template in your My Elements from a manifest and an ES module (read get_element_guide first). The draft is stored even when the check finds problems; the answer carries the full check: each problem with its code, message and line / column (module) or JSON path (manifest). Fix them with update_element_template, then publish_element_template. The template id is the manifest id.

The draft is stored even when the check finds problems; the answer lists them with line and column.

manifest · object or string · required

The manifest as a JSON object (or its text): id, name, description, family, apiVersion 1, params, placement, capabilities, budget.

module · string · required

The ES module text: one default export, a synchronous setup(ctx). (up to 65536 characters)

Example: create_element_template { "manifest": { "id": "lanterns", … }, "module": "export default function setup (ctx) { … }" }

update_element_template · Update an Element template draft

Replaces the draft of one of your own templates (the manifest, the module or both; the one not given stays) and answers the new check. Published versions never change; publish_element_template makes the draft a new version. The manifest id cannot change.

template · string · required

A template id (lowercase letters, digits and hyphens), as list_element_templates lists it. (at least 2 characters, up to 48 characters, a fixed format)

manifest · object or string · optional

The new manifest (JSON object or text).

module · string · optional

The new module text. (up to 65536 characters)

Example: update_element_template { "template": "lanterns", "module": "…" }

validate_element_template · Check an Element template

Checks a template without storing anything: give your own template id (its draft) or a manifest and module. Answers ok, every problem with line / column or JSON path, the declared and used capabilities, and whether it bakes (no code runs while visitors watch). When the check has no errors the template is also run headlessly for a few seconds at its default placement in front of a neutral backdrop, as a visitor's viewer runs it (time is simulated, so the same call gives the same answer): headlessRun reports runtime errors with stage and line / column, the measured budgets against their limits, whether it baked, what it asked the viewer to do (links, sounds, stored values) and preview pictures. Optional inputSequence plays it (see get_element_guide section input_sequence): selects on named objects, drags, button presses and thumbstick values at given times, with previews at the times you list, so you can play your game and watch the score. A run that does not fit the time limit stops with reason time_budget and answers what it reached. A headless run counts against the render limit.

Writes nothing. A clean template is also run headlessly (a few seconds, or as long as its inputSequence asks) and answers runtime problems, measured budgets, whether it bakes and preview pictures; the run counts against the render limit.

template · string · optional

One of your own templates: its draft is checked. (at least 2 characters, up to 48 characters, a fixed format)

manifest · object or string · optional

A manifest to check (with module), instead of a template id.

module · string · optional

A module to check (with manifest). (up to 65536 characters)

inputSequence · any · optional

A scripted play-through: { steps: [{ at, action, … }], previews: [ms] } (get_element_guide section input_sequence).

Example: validate_element_template { "template": "lanterns" }

publish_element_template · Publish an Element template

Publishes the draft of one of your own templates as a new version (needs a clean check; refused with check_failed and the problems otherwise). Versions are immutable and content-addressed; publishing the same content again returns the existing latest version. Instances keep the version they pin until upgrade_element.

Needs a clean check. Versions are immutable; placed Elements keep theirs until upgrade_element.

template · string · required

A template id (lowercase letters, digits and hyphens), as list_element_templates lists it. (at least 2 characters, up to 48 characters, a fixed format)

Example: publish_element_template { "template": "lanterns" }

fork_element_template · Fork an Element template

Copies a version of an Orbix360 template or of one of your own into a new template in your My Elements, with version 1 published, so you can change it. Orbix360 templates that use the viewer's own services (video, portal, hotspot element, text) cannot be forked. The new id is templateId, or "<source>-copy".

source · object · required

The template to copy: { collection, template, version? }.

source.collection · one of: orbix, user · required

"orbix" = Orbix360's collection; "user" = your own My Elements.

source.template · string · required

A template id (lowercase letters, digits and hyphens), as list_element_templates lists it. (at least 2 characters, up to 48 characters, a fixed format)

source.version · integer · optional

A published version number; omit for the latest. (at least 1)

templateId · string · optional

The new template's id; default "<source>-copy". (at least 2 characters, up to 48 characters, a fixed format)

Example: fork_element_template { "source": { "collection": "orbix", "template": "fireflies" } }

delete_element_template · Delete an Element template

Deletes one of your own templates. While any tour uses it the call is refused with template_in_use and the usage per version; ask the owner, then call again with confirm: true. The draft and unused versions are removed; versions placed copies pin stay so those copies keep working. Cannot be undone.

Cannot be undone. While tours use the template it needs confirm: true; versions placed Elements use are kept.

template · string · required

A template id (lowercase letters, digits and hyphens), as list_element_templates lists it. (at least 2 characters, up to 48 characters, a fixed format)

confirm · boolean · optional

true to delete although tours use it (the owner agreed).

Example: delete_element_template { "template": "lanterns" }

convert_element_template · Convert an older Element template

Converts one of your older-format Elements (the markup templates list_element_templates lists under olderTemplates) into a script template in your My Elements, with version 1 published, drawing the same parts at the same places. The original is not changed and tours keep using it. When some parts cannot be converted the call refuses with confirm_required and lists them; tell the owner and call again with confirm: true. checkOnly: true answers the generated manifest and module without storing anything. Calling again for an unchanged original answers the template already made (existing: true).

The original older Element is never changed; tours keep using it until they are moved to the converted template.

When parts would be left out it answers confirm_required: tell the owner, then call again with confirm: true.

templateId · string · required

The older Element's id, as list_element_templates gives it in olderTemplates. (a fixed format)

confirm · boolean · optional

true: convert even though some parts are left out (after telling the owner which).

checkOnly · boolean · optional

true: only answer what the conversion would be (outcome, parts left out, manifest and module); nothing is stored.

Example: convert_element_template { "templateId": "5639584813678592", "checkOnly": true }

list_elements · List the Elements of a tour

Lists the Elements placed in a tour (or one scene). Script Elements come with their template reference, parameters, yaw / pitch / distance from the viewer, whether the viewer can run them (runnable, skip) and upgradeAvailable when a newer version of their template is published. Older Elements (A-Frame form) are listed as read-only summaries with their kind.

tourId · string · required

The tour id, as list_tours and get_tour list it. (at least 1 character)

sceneId · string or integer · optional

The scene (photo) id, as get_tour lists it.

Example: list_elements { "tourId": "…" }

place_element · Place an Element

Places a new Element of a template in a scene: give the template ({ collection, template, version? }; the latest published version by default), parameter values (missing ones get their defaults; a file parameter takes { "url": "https://…" }), and for a relative template the direction yaw / pitch (read them off render_view) and a distance in metres. Absolute templates stand where their manifest says; scene-wide templates (a sky) take no placement and at most one per scene. The Element faces the viewer unless its template keeps a fixed rotation. Check the result with list_elements and with render_view centred on it (it draws Script Elements), then give the owner the sceneUrl.

Check the placement with render_view centred on the Element: it draws Script Elements. A file parameter takes { "url": "https://…" }.

tourId · string · required

The tour id, as list_tours and get_tour list it. (at least 1 character)

sceneId · string or integer · required

The scene (photo) id, as get_tour lists it.

template · object · required

Which template: { collection, template, version? }.

template.collection · one of: orbix, user · required

"orbix" = Orbix360's collection; "user" = your own My Elements.

template.template · string · required

A template id (lowercase letters, digits and hyphens), as list_element_templates lists it. (at least 2 characters, up to 48 characters, a fixed format)

template.version · integer · optional

A published version number; omit for the latest. (at least 1)

params · object · optional

Parameter values by key, as the template's manifest declares them (get_element_template). A file parameter takes { "url": "https://…" } (fetched and checked) or null (cleared); a scene parameter takes a scene id of this tour.

name · string · optional

The Element's name in the editor; default the template name (numbered). (at least 1 character, up to 100 characters)

yaw · number · optional

Direction of the Element from the viewer, degrees on the scene's photo: 0 = the photo's centre column, positive to the right; wrapped into (-180, 180]. Required for a relative template when placing.

pitch · number · optional

Height of the direction, degrees: 0 = the horizon, +90 = straight up, -90 = straight down; defaults to the template's own pitch, else 0. (at least -90, at most 90)

distance · number · optional

Metres from the viewer (0.3 to 200); defaults to the template's own distance. (at least 0.3, at most 200)

rotation · object · optional

Rotation in degrees { x, y, z }; replaces the computed one (by default the Element faces the viewer).

rotation.x · number · required

X component.

rotation.y · number · required

Y component (up).

rotation.z · number · required

Z component.

scale · object · optional

Scale factors { x, y, z } (none of them 0).

scale.x · number · required

X component.

scale.y · number · required

Y component (up).

scale.z · number · required

Z component.

Example: place_element { "tourId": "…", "sceneId": "…", "template": { "collection": "orbix", "template": "fireflies" }, "yaw": 40, "pitch": -5, "distance": 4 }

update_element · Update an Element

Changes one Script Element (ids from list_elements or get_tour): its name, some parameter values (a file parameter takes { "url": "https://…" } or null) and / or its place. Giving yaw, pitch or distance moves it (the others keep their current values) and it turns to keep facing the viewer; rotation and scale replace. Everything changes in one edit; nothing is written when nothing changes. Older (A-Frame) Elements cannot be changed here.

tourId · string · required

The tour id, as list_tours and get_tour list it. (at least 1 character)

instanceId · string · required

The Element id, as list_elements lists it. (at least 1 character, up to 200 characters)

name · string · optional

A new name. (at least 1 character, up to 100 characters)

params · object · optional

Parameter values by key, as the template's manifest declares them (get_element_template). A file parameter takes { "url": "https://…" } (fetched and checked) or null (cleared); a scene parameter takes a scene id of this tour.

yaw · number · optional

Direction of the Element from the viewer, degrees on the scene's photo: 0 = the photo's centre column, positive to the right; wrapped into (-180, 180]. Required for a relative template when placing.

pitch · number · optional

Height of the direction, degrees: 0 = the horizon, +90 = straight up, -90 = straight down; defaults to the template's own pitch, else 0. (at least -90, at most 90)

distance · number · optional

Metres from the viewer (0.3 to 200); defaults to the template's own distance. (at least 0.3, at most 200)

rotation · object · optional

Rotation in degrees { x, y, z }; replaces the computed one (by default the Element faces the viewer).

rotation.x · number · required

X component.

rotation.y · number · required

Y component (up).

rotation.z · number · required

Z component.

scale · object · optional

Scale factors { x, y, z } (none of them 0).

scale.x · number · required

X component.

scale.y · number · required

Y component (up).

scale.z · number · required

Z component.

Example: update_element { "tourId": "…", "instanceId": "…", "params": { "color": "#ffaa00" } }

upgrade_element · Upgrade an Element

Moves one Script Element to the latest (or a named) published version of its template. Parameter values the new version still accepts are kept, new parameters get their defaults and parameters it no longer has are dropped; the answer lists each. An Element already on that version is unchanged.

tourId · string · required

The tour id, as list_tours and get_tour list it. (at least 1 character)

instanceId · string · required

The Element id, as list_elements lists it. (at least 1 character, up to 200 characters)

version · integer · optional

A published version number; omit for the latest. (at least 1)

Example: upgrade_element { "tourId": "…", "instanceId": "…" }

remove_element · Remove an Element

Removes one Script Element from its scene (ids from list_elements). Other Elements are untouched; older (A-Frame) Elements cannot be removed here.

tourId · string · required

The tour id, as list_tours and get_tour list it. (at least 1 character)

instanceId · string · required

The Element id, as list_elements lists it. (at least 1 character, up to 200 characters)

Example: remove_element { "tourId": "…", "instanceId": "…" }

create_element_file_upload · Upload a file for an Element

Prepares an upload for one file parameter of a placed Script Element (a picture, sound, model or video the template's manifest declares as type "file"). Answers a shell command (PUT the file; for agents with a shell) and an uploadPage link (give it to the owner in a chat: they drop the file there while signed in; it works once, for 2 hours). Then call get_element_file_status with the uploadId: once the file has arrived and passed the parameter's file rule, its address is written into the Element. For a file at a public https URL, pass { "url": … } to place_element or update_element instead.

Run the command, or give the owner the upload page (2 hours, once); then poll get_element_file_status.

tourId · string · required

The tour id, as list_tours and get_tour list it. (at least 1 character)

instanceId · string · required

The Element id, as list_elements lists it. (at least 1 character, up to 200 characters)

param · string · required

The file parameter's key, as get_element_template lists it. (at least 1 character, up to 64 characters, a fixed format)

filename · string · required

The local file's name; its extension must be one the parameter accepts (get_element_guide section params). (at least 1 character, up to 200 characters)

fileSize · integer · optional

The file's size in bytes, when known; the command's upload is then bound to it. (more than 0)

Example: create_element_file_upload { "tourId": "…", "instanceId": "…", "param": "pop", "filename": "pop.mp3" }

get_element_file_status · Check Element file uploads

Answers the state of 1 to 10 uploads made with create_element_file_upload: pending_upload (no file yet), processing, ready (with the address now stored in the Element's parameter), failed (with the code, e.g. unsupported_file or file_too_large) or not_found. A file that has arrived is checked against the parameter's rule and written in when this is called.

tourId · string · required

The tour id, as list_tours and get_tour list it. (at least 1 character)

uploadIds · list of string · required

Upload ids from create_element_file_upload. (at least 1 item, up to 10 items)

Example: get_element_file_status { "tourId": "…", "uploadIds": ["…"] }